build based on 5706a47

previews/PR158/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-26T10:17:30","documenter_version":"1.7.0"}}
+{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-26T10:44:41","documenter_version":"1.7.0"}}

previews/PR158/getting-started/index.html

@@ -10,7 +10,7 @@
 components[3] (prior = 0.2000): Distributions.Normal{Float64}(μ=20.0, σ=1.5)
 </code></pre><p>This is a simple 1-dimensional distribution, so let&#39;s visualize it:</p><pre><code class="language-julia hljs">using StatsPlots
 figsize = (800, 400)
-plot(target_distribution; components=false, label=nothing, size=figsize)</code></pre><img src="ecb99dd6.svg" alt="Example block output"/><p>We can convert a <code>Distribution</code> from <a href="https://github.com/JuliaStats/Distributions.jl">Distributions.jl</a> into something we can pass to <code>sample</code> for many different samplers by implementing the <a href="https://github.com/tpapp/LogDensityProblems.jl">LogDensityProblems.jl</a> interface:</p><pre><code class="language-julia hljs">using LogDensityProblems: LogDensityProblems
+plot(target_distribution; components=false, label=nothing, size=figsize)</code></pre><img src="0f1d5f0e.svg" alt="Example block output"/><p>We can convert a <code>Distribution</code> from <a href="https://github.com/JuliaStats/Distributions.jl">Distributions.jl</a> into something we can pass to <code>sample</code> for many different samplers by implementing the <a href="https://github.com/tpapp/LogDensityProblems.jl">LogDensityProblems.jl</a> interface:</p><pre><code class="language-julia hljs">using LogDensityProblems: LogDensityProblems
 
 struct DistributionLogDensity{D}
     d::D
@@ -57,9 +57,9 @@
  </span><span class="sgr90">     Symbol   Float64   Float64   Float64   Float64   Float64
 
            x   -5.6359   -3.2669   -1.4454    2.5327    5.3961
-</span></span></code></pre><pre><code class="language-julia hljs">plot(chain; size=figsize)</code></pre><img src="e62bf488.svg" alt="Example block output"/><p>This doesn&#39;t look quite like what we&#39;re expecting.</p><pre><code class="language-julia hljs">plot(target_distribution; components=false, linewidth=2)
+</span></span></code></pre><pre><code class="language-julia hljs">plot(chain; size=figsize)</code></pre><img src="40410278.svg" alt="Example block output"/><p>This doesn&#39;t look quite like what we&#39;re expecting.</p><pre><code class="language-julia hljs">plot(target_distribution; components=false, linewidth=2)
 density!(chain)
-plot!(size=figsize)</code></pre><img src="529abdd5.svg" alt="Example block output"/><p>Notice how <code>chain</code> has zero probability mass in the left-most component of the mixture!</p><p>Let&#39;s instead try to use a <em>tempered</em> version of <code>RWMH</code>. <em>But</em> before we do that, we need to make sure that AdvancedMH.jl is compatible with MCMCTempering.jl.</p><p>To do that we need to implement two methods. First we need to tell MCMCTempering how to extract the parameters, and potentially the log-probabilities, from a <code>AdvancedMH.Transition</code>:</p><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="MCMCTempering.getparams_and_logprob-getting-started" href="#MCMCTempering.getparams_and_logprob-getting-started"><code>MCMCTempering.getparams_and_logprob</code></a> — <span class="docstring-category">Function</span><span class="is-flex-grow-1 docstring-article-toggle-button" title="Collapse docstring"></span></header><section><div><pre><code class="language-julia hljs">getparams_and_logprob([model, ]state)</code></pre><p>Return a vector of parameters from the <code>state</code>.</p><p>See also: <a href="../api/#MCMCTempering.setparams_and_logprob!!"><code>setparams_and_logprob!!</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/MCMCTempering.jl/blob/1a5a69308c718e5c8e965e5020aa60bb34a394a9/src/abstractmcmc.jl#L26-L32">source</a></section></article><p>And similarly, we need a way to <em>update</em> the parameters and the log-probabilities of a <code>AdvancedMH.Transition</code>:</p><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="MCMCTempering.setparams_and_logprob!!-getting-started" href="#MCMCTempering.setparams_and_logprob!!-getting-started"><code>MCMCTempering.setparams_and_logprob!!</code></a> — <span class="docstring-category">Function</span><span class="is-flex-grow-1 docstring-article-toggle-button" title="Collapse docstring"></span></header><section><div><pre><code class="language-julia hljs">setparams_and_logprob!!([model, ]state, params)</code></pre><p>Set the parameters in the state to <code>params</code>, possibly mutating if it makes sense.</p><p>See also: <a href="../api/#MCMCTempering.getparams_and_logprob"><code>getparams_and_logprob</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/MCMCTempering.jl/blob/1a5a69308c718e5c8e965e5020aa60bb34a394a9/src/abstractmcmc.jl#L35-L41">source</a></section></article><p>Luckily, implementing these is quite easy:</p><pre><code class="language-julia hljs">using MCMCTempering
+plot!(size=figsize)</code></pre><img src="1f9663ec.svg" alt="Example block output"/><p>Notice how <code>chain</code> has zero probability mass in the left-most component of the mixture!</p><p>Let&#39;s instead try to use a <em>tempered</em> version of <code>RWMH</code>. <em>But</em> before we do that, we need to make sure that AdvancedMH.jl is compatible with MCMCTempering.jl.</p><p>To do that we need to implement two methods. First we need to tell MCMCTempering how to extract the parameters, and potentially the log-probabilities, from a <code>AdvancedMH.Transition</code>:</p><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="MCMCTempering.getparams_and_logprob-getting-started" href="#MCMCTempering.getparams_and_logprob-getting-started"><code>MCMCTempering.getparams_and_logprob</code></a> — <span class="docstring-category">Function</span><span class="is-flex-grow-1 docstring-article-toggle-button" title="Collapse docstring"></span></header><section><div><pre><code class="language-julia hljs">getparams_and_logprob([model, ]state)</code></pre><p>Return a vector of parameters from the <code>state</code>.</p><p>See also: <a href="../api/#MCMCTempering.setparams_and_logprob!!"><code>setparams_and_logprob!!</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/MCMCTempering.jl/blob/5706a4732df5d013cea707a139de33e2e8875b63/src/abstractmcmc.jl#L26-L32">source</a></section></article><p>And similarly, we need a way to <em>update</em> the parameters and the log-probabilities of a <code>AdvancedMH.Transition</code>:</p><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="MCMCTempering.setparams_and_logprob!!-getting-started" href="#MCMCTempering.setparams_and_logprob!!-getting-started"><code>MCMCTempering.setparams_and_logprob!!</code></a> — <span class="docstring-category">Function</span><span class="is-flex-grow-1 docstring-article-toggle-button" title="Collapse docstring"></span></header><section><div><pre><code class="language-julia hljs">setparams_and_logprob!!([model, ]state, params)</code></pre><p>Set the parameters in the state to <code>params</code>, possibly mutating if it makes sense.</p><p>See also: <a href="../api/#MCMCTempering.getparams_and_logprob"><code>getparams_and_logprob</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/MCMCTempering.jl/blob/5706a4732df5d013cea707a139de33e2e8875b63/src/abstractmcmc.jl#L35-L41">source</a></section></article><p>Luckily, implementing these is quite easy:</p><pre><code class="language-julia hljs">using MCMCTempering
 
 MCMCTempering.getparams_and_logprob(transition::AdvancedMH.Transition) = transition.params, transition.lp
 function MCMCTempering.setparams_and_logprob!!(transition::AdvancedMH.Transition, params, lp)
@@ -136,7 +136,7 @@
 end
 density!(chain_tempered_all[1], color=&quot;green&quot;, size=figsize)
 plot!(size=figsize)</code></pre><p>Works like a charm!</p><p><em>But</em> we&#39;re recomputing both the logdensity and the gradient of the logdensity upon every <a href="../api/#MCMCTempering.setparams_and_logprob!!"><code>MCMCTempering.setparams_and_logprob!!</code></a> above! This seems wholly unnecessary in the tempering case, since</p><p class="math-container">\[\pi_{\beta_1}(x) = \pi(x)^{\beta_1} = \big( \pi(x)^{\beta_2} \big)^{\beta_1 / \beta_2} = \pi_{\beta_2}^{\beta_1 / \beta_2}\]</p><p>i.e. if <code>model</code> in the above is tempered with <span>$\beta_1$</span> and the <code>params</code> are coming from a model with <span>$\beta_2$</span>, we can could just compute it as</p><pre><code class="language-julia hljs">(β_1 / β_2) * logprob</code></pre><p>and similarly for the gradient! Luckily, it&#39;s possible to tell MCMCTempering that this should be done by overloading the <a href="#MCMCTempering.state_from"><code>MCMCTempering.state_from</code></a> method. In particular, we&#39;ll specify that when we&#39;re working with two models of type <a href="../api/#MCMCTempering.TemperedLogDensityProblem"><code>MCMCTempering.TemperedLogDensityProblem</code></a> and two states of type <code>AdvancedHMC.HMCState</code>, then we can just re-use scale the logdensity and gradient computation from the <a href="#MCMCTempering.state_from"><code>MCMCTempering.state_from</code></a> to get the quantities we want, thus avoiding unnecessary computations:</p><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="MCMCTempering.state_from" href="#MCMCTempering.state_from"><code>MCMCTempering.state_from</code></a> — <span class="docstring-category">Function</span><span class="is-flex-grow-1 docstring-article-toggle-button" title="Collapse docstring"></span></header><section><div><pre><code class="language-julia hljs">state_from(model_source, state_target, state_source)
-state_from(model_source, model_target, state_target, state_source)</code></pre><p>Return a new state similar to <code>state_target</code> but updated from <code>state_source</code>, which could be a different type of state.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/MCMCTempering.jl/blob/1a5a69308c718e5c8e965e5020aa60bb34a394a9/src/abstractmcmc.jl#L44-L50">source</a></section></article><pre><code class="language-julia hljs">using AbstractMCMC: AbstractMCMC
+state_from(model_source, model_target, state_target, state_source)</code></pre><p>Return a new state similar to <code>state_target</code> but updated from <code>state_source</code>, which could be a different type of state.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/TuringLang/MCMCTempering.jl/blob/5706a4732df5d013cea707a139de33e2e8875b63/src/abstractmcmc.jl#L44-L50">source</a></section></article><pre><code class="language-julia hljs">using AbstractMCMC: AbstractMCMC
 
 function MCMCTempering.state_from(
     # AdvancedHMC.jl works with `LogDensityModel`, and by default `AbstractMCMC` will wrap
@@ -183,4 +183,4 @@
     density!(chain_tempered, color=&quot;green&quot;, alpha=inv(sqrt(length(chain_tempered_all))))
 end
 density!(chain_tempered_all[1], color=&quot;green&quot;, size=figsize)
-plot!(size=figsize)</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Home</a><a class="docs-footer-nextpage" href="../api/">API »</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.7.0 on <span class="colophon-date" title="Thursday 26 September 2024 10:17">Thursday 26 September 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+plot!(size=figsize)</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Home</a><a class="docs-footer-nextpage" href="../api/">API »</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.7.0 on <span class="colophon-date" title="Thursday 26 September 2024 10:44">Thursday 26 September 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>