build based on c982d25

Author: Documenter.jl

dev/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-08-31T02:53:13","documenter_version":"1.6.0"}}
+{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-08-31T02:54:11","documenter_version":"1.6.0"}}

dev/abstractmcmc_demo.svg

@@ -8,7 +8,7 @@
 \theta_n &\sim \operatorname{Uniform}\left\{ \theta \in \mathbb{S}^{d-1} \mid \varrho^{(1)}\left(r_{n-1} \theta\right) > T_n \right\} \\
 r_n      &\sim \operatorname{Uniform}\left\{ r \in \mathbb{R}_{\geq 0} \mid \varrho^{(1)}\left(r \theta_n\right) > T_n \right\} \\
 x_n      &= \theta_n r_n,
-\end{aligned}\]</p><p>where <span>$T_n$</span> is the usual acceptance threshold auxiliary variable, while <span>$\theta$</span> and <span>$r$</span> are the sampler states in polar coordinates. The Gibbs steps on <span>$\theta$</span> and <span>$r$</span> are implemented through specialized shrinkage procedures.</p><p>The only tunable parameter of the algorithm is the size of the search interval (window) of the shrinkage sampler for the radius variable <span>$r$</span>.</p><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>The kernel corresponding to this sampler is defined on an <strong>augmented state space</strong> and cannot directly perform a transition on <span>$x$</span>. This also means that the corresponding kernel is not reversible with respect to <span>$x$</span>.</p></div></div><h2 id="Interface"><a class="docs-heading-anchor" href="#Interface">Interface</a><a id="Interface-1"></a><a class="docs-heading-anchor-permalink" href="#Interface" title="Permalink"></a></h2><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>By the nature of polar coordinates, GPSS only works reliably for targets with dimension at least <span>$d \geq 2$</span>.</p></div></div><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="SliceSampling.GibbsPolarSlice" href="#SliceSampling.GibbsPolarSlice"><code>SliceSampling.GibbsPolarSlice</code></a> — <span class="docstring-category">Type</span><span class="is-flex-grow-1 docstring-article-toggle-button" title="Collapse docstring"></span></header><section><div><pre><code class="language-julia hljs">GibbsPolarSlice(w; max_proposals)</code></pre><p>Gibbsian polar slice sampling algorithm by P. Schär, M. Habeck, and D. Rudolf <sup class="footnote-reference"><a id="citeref-SHR2023" href="#footnote-SHR2023">[SHR2023]</a></sup>.</p><p><strong>Arguments</strong></p><ul><li><code>w::Real</code>: Initial window size for the radius shrinkage procedure.</li></ul><p><strong>Keyword Arguments</strong></p><ul><li><code>w::Real</code>: Initial window size for the radius shrinkage procedure</li><li><code>max_proposals::Int</code>: Maximum number of proposals allowed until throwing an error (default: <code>typemax(Int)</code>).</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/SliceSampling.jl/blob/76e9f14fd9c58bceba0d45ef188b201172425351/src/multivariate/gibbspolar.jl#L2-L13">source</a></section></article><div class="admonition is-warning"><header class="admonition-header">Warning</header><div class="admonition-body"><p>When initializing the chain (<em>e.g.</em> the <code>initial_params</code> keyword arguments in <code>AbstractMCMC.sample</code>), it is necessary to inialize from a point <span>$x_0$</span> that has a sensible norm <span>$\lVert x_0 \rVert &gt; 0$</span>, otherwise, the chain will start from a pathologic point in polar coordinates. This might even result in the sampler getting stuck in an infinite loop. (This can be prevented by setting <code>max_proposals</code>.) If <span>$\lVert x_0 \rVert \leq 10^{-5}$</span>, the current implementation will display a warning. </p></div></div><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>For Turing users: <code>Turing</code> might change <code>initial_params</code> to match the support of the posterior. This might lead to <span>$\lVert x_0 \rVert$</span> being small, even though the vector you passed to<code>initial_params</code> has a sufficiently large norm. If this is suspected, simply try a different initialization value.</p></div></div><h2 id="Demonstration"><a class="docs-heading-anchor" href="#Demonstration">Demonstration</a><a id="Demonstration-1"></a><a class="docs-heading-anchor-permalink" href="#Demonstration" title="Permalink"></a></h2><p>As illustrated in the original paper, GPSS shows good performance on heavy-tailed targets despite being a multivariate slice sampler. Consider a 10-dimensional Student-<span>$t$</span> target with 1-degree of freedom (this corresponds to a multivariate Cauchy):</p><pre><code class="language-julia hljs">using Distributions
+\end{aligned}\]</p><p>where <span>$T_n$</span> is the usual acceptance threshold auxiliary variable, while <span>$\theta$</span> and <span>$r$</span> are the sampler states in polar coordinates. The Gibbs steps on <span>$\theta$</span> and <span>$r$</span> are implemented through specialized shrinkage procedures.</p><p>The only tunable parameter of the algorithm is the size of the search interval (window) of the shrinkage sampler for the radius variable <span>$r$</span>.</p><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>The kernel corresponding to this sampler is defined on an <strong>augmented state space</strong> and cannot directly perform a transition on <span>$x$</span>. This also means that the corresponding kernel is not reversible with respect to <span>$x$</span>.</p></div></div><h2 id="Interface"><a class="docs-heading-anchor" href="#Interface">Interface</a><a id="Interface-1"></a><a class="docs-heading-anchor-permalink" href="#Interface" title="Permalink"></a></h2><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>By the nature of polar coordinates, GPSS only works reliably for targets with dimension at least <span>$d \geq 2$</span>.</p></div></div><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="SliceSampling.GibbsPolarSlice" href="#SliceSampling.GibbsPolarSlice"><code>SliceSampling.GibbsPolarSlice</code></a> — <span class="docstring-category">Type</span><span class="is-flex-grow-1 docstring-article-toggle-button" title="Collapse docstring"></span></header><section><div><pre><code class="language-julia hljs">GibbsPolarSlice(w; max_proposals)</code></pre><p>Gibbsian polar slice sampling algorithm by P. Schär, M. Habeck, and D. Rudolf <sup class="footnote-reference"><a id="citeref-SHR2023" href="#footnote-SHR2023">[SHR2023]</a></sup>.</p><p><strong>Arguments</strong></p><ul><li><code>w::Real</code>: Initial window size for the radius shrinkage procedure.</li></ul><p><strong>Keyword Arguments</strong></p><ul><li><code>w::Real</code>: Initial window size for the radius shrinkage procedure</li><li><code>max_proposals::Int</code>: Maximum number of proposals allowed until throwing an error (default: <code>typemax(Int)</code>).</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/SliceSampling.jl/blob/c982d253aae2fdca36cc47264608e8c8e165ee30/src/multivariate/gibbspolar.jl#L2-L13">source</a></section></article><div class="admonition is-warning"><header class="admonition-header">Warning</header><div class="admonition-body"><p>When initializing the chain (<em>e.g.</em> the <code>initial_params</code> keyword arguments in <code>AbstractMCMC.sample</code>), it is necessary to inialize from a point <span>$x_0$</span> that has a sensible norm <span>$\lVert x_0 \rVert &gt; 0$</span>, otherwise, the chain will start from a pathologic point in polar coordinates. This might even result in the sampler getting stuck in an infinite loop. (This can be prevented by setting <code>max_proposals</code>.) If <span>$\lVert x_0 \rVert \leq 10^{-5}$</span>, the current implementation will display a warning. </p></div></div><div class="admonition is-info"><header class="admonition-header">Info</header><div class="admonition-body"><p>For Turing users: <code>Turing</code> might change <code>initial_params</code> to match the support of the posterior. This might lead to <span>$\lVert x_0 \rVert$</span> being small, even though the vector you passed to<code>initial_params</code> has a sufficiently large norm. If this is suspected, simply try a different initialization value.</p></div></div><h2 id="Demonstration"><a class="docs-heading-anchor" href="#Demonstration">Demonstration</a><a id="Demonstration-1"></a><a class="docs-heading-anchor-permalink" href="#Demonstration" title="Permalink"></a></h2><p>As illustrated in the original paper, GPSS shows good performance on heavy-tailed targets despite being a multivariate slice sampler. Consider a 10-dimensional Student-<span>$t$</span> target with 1-degree of freedom (this corresponds to a multivariate Cauchy):</p><pre><code class="language-julia hljs">using Distributions
 using Turing
 using SliceSampling
 using LinearAlgebra
@@ -27,4 +27,4 @@
 p1 = Plots.plot(1:n_samples, latent_chain[:,1,:], ylims=[-10,10], label=&quot;LSS&quot;)
 p2 = Plots.plot(1:n_samples, polar_chain[:,1,:],  ylims=[-10,10], label=&quot;GPSS&quot;)
 plot(p1, p2, layout = l)
-savefig(&quot;student_latent_gpss.svg&quot;)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">&quot;/home/runner/work/SliceSampling.jl/SliceSampling.jl/docs/build/student_latent_gpss.svg&quot;</code></pre><p><img src="../student_latent_gpss.svg" alt/></p><p>Clearly, GPSS is better at exploring the deep tails compared to the <a href="../latent_slice/#latent">latent slice sampler</a> (LSS) despite having a similar per-iteration cost.</p><section class="footnotes is-size-7"><ul><li class="footnote" id="footnote-SHR2023"><a class="tag is-link" href="#citeref-SHR2023">SHR2023</a>Schär, P., Habeck, M., &amp; Rudolf, D. (2023, July). Gibbsian polar slice sampling. In International Conference on Machine Learning.</li><li class="footnote" id="footnote-RR2002"><a class="tag is-link" href="#citeref-RR2002">RR2002</a>Roberts, G. O., &amp; Rosenthal, J. S. (2002). The polar slice sampler. Stochastic Models, 18(2), 257-280.</li></ul></section></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../latent_slice/">« Latent Slice Sampling</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.6.0 on <span class="colophon-date" title="Saturday 31 August 2024 02:53">Saturday 31 August 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+savefig(&quot;student_latent_gpss.svg&quot;)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">&quot;/home/runner/work/SliceSampling.jl/SliceSampling.jl/docs/build/student_latent_gpss.svg&quot;</code></pre><p><img src="../student_latent_gpss.svg" alt/></p><p>Clearly, GPSS is better at exploring the deep tails compared to the <a href="../latent_slice/#latent">latent slice sampler</a> (LSS) despite having a similar per-iteration cost.</p><section class="footnotes is-size-7"><ul><li class="footnote" id="footnote-SHR2023"><a class="tag is-link" href="#citeref-SHR2023">SHR2023</a>Schär, P., Habeck, M., &amp; Rudolf, D. (2023, July). Gibbsian polar slice sampling. In International Conference on Machine Learning.</li><li class="footnote" id="footnote-RR2002"><a class="tag is-link" href="#citeref-RR2002">RR2002</a>Roberts, G. O., &amp; Rosenthal, J. S. (2002). The polar slice sampler. Stochastic Models, 18(2), 257-280.</li></ul></section></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../latent_slice/">« Latent Slice Sampling</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.6.0 on <span class="colophon-date" title="Saturday 31 August 2024 02:54">Saturday 31 August 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>