diff --git a/404.html b/404.html
index dbe6bc7f..8f4bd230 100644
--- a/404.html
+++ b/404.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="https://canmod.github.io/macpan2/index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/CONTRIBUTING.html b/CONTRIBUTING.html
index 9fd4a5eb..a4c3c47c 100644
--- a/CONTRIBUTING.html
+++ b/CONTRIBUTING.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/LICENSE-text.html b/LICENSE-text.html
index 8e142252..287756db 100644
--- a/LICENSE-text.html
+++ b/LICENSE-text.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/FAQs.html b/articles/FAQs.html
index b14286b4..f6a725ae 100644
--- a/articles/FAQs.html
+++ b/articles/FAQs.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
@@ -145,13 +145,14 @@ <h3 id="why-do-some-of-the-functions-start-with-mp_tmb_">Why do some of the func
 </h3>
 <p>The <code>tmb</code> part refers to the <a href="https://github.com/kaskr/adcomp" class="external-link">TMB</a> package, on which
 <code>macpan2</code> is built. We hope to one day use other
-computational engines (e.g., <a href="TODO">stan</a>), at which point
-users will be able to see what computational engine is being used in
-their scripts. But for now <code>tmb</code> is the only computational
-engine and so the only thing indicated by <code>mp_tmb_</code> is that
-you are using a function that is intended to be specific to computations
-with TMB. Functions that do not start with <code>mp_tmb_</code> should
-be engine-agnostic and able to be used with any engine.</p>
+computational engines (e.g., <a href="https://mc-stan.org/" class="external-link">stan</a>),
+at which point users will be able to see what computational engine is
+being used in their scripts. But for now <code>tmb</code> is the only
+computational engine and so the only thing indicated by
+<code>mp_tmb_</code> is that you are using a function that is intended
+to be specific to computations with TMB. Functions that do not start
+with <code>mp_tmb_</code> should be engine-agnostic and able to be used
+with any engine when and if such engines are supported.</p>
 </div>
 </div>
 <div class="section level2">
@@ -167,10 +168,11 @@ <h3 id="what-does-mean">What does <code>|&gt;</code> mean?<a class="anchor" aria
 <div class="section level3">
 <h3 id="why-do-i-see-weird-symbols-at-the-start-of-lines">Why do I see weird symbols at the start of lines?<a class="anchor" aria-label="anchor" href="#why-do-i-see-weird-symbols-at-the-start-of-lines"></a>
 </h3>
-<p>We start lines with characters that many people put at the end of
-lines, such as the commas, plus signs and the <a href="https://www.tidyverse.org/blog/2023/04/base-vs-magrittr-pipe/#pipes" class="external-link">base
-R pipe</a>. These continuation characters tell R that there is more code
-that is included in an expression. We prefer to put these characters at
+<p>In many of our examples we start lines with characters that many
+people put at the end of lines, such as the commas, plus signs and the
+<a href="https://www.tidyverse.org/blog/2023/04/base-vs-magrittr-pipe/#pipes" class="external-link">base
+R pipe</a>. These characters tell R how the code on the rest of the line
+is to combined with previous lines. We prefer to put these characters at
 the start of lines because it makes it slightly easier to comment lines
 out. Note that for this approach to work you need to wrap these
 continued expressions in parentheses. See the <a href="https://canmod.github.io/macpan2/articles/quickstart.html">quickstart</a>
@@ -288,8 +290,8 @@ <h3 id="should-i-worry-about-nanan-function-evaluation-warnings">Should I worry
 <pre><code>Warning messages:
 1: In (function (start, objective, gradient = NULL, hessian = NULL,  :
   NA/NaN function evaluation</code></pre>
-<p>These are usually nothing to worry about, though you should take note
-of them. Typically this warning indicates that the optimizer tried
+<p>This is usually nothing to worry about, though you should take note
+of it. Typically this warning indicates that the optimizer tried
 parameter values that led the objective function (i.e., the negative log
 posterior density) to be non-numeric. Usually, the opimizer is smart
 enough (if it is possible) to get back on track. The key thing to watch
diff --git a/articles/calibration.html b/articles/calibration.html
index 80843245..67a61399 100644
--- a/articles/calibration.html
+++ b/articles/calibration.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/calibration_advanced.html b/articles/calibration_advanced.html
index a1b34e7d..113234c0 100644
--- a/articles/calibration_advanced.html
+++ b/articles/calibration_advanced.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/composing_simulation_models.html b/articles/composing_simulation_models.html
index bfaa8270..d34e52c0 100644
--- a/articles/composing_simulation_models.html
+++ b/articles/composing_simulation_models.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/cpp_side.html b/articles/cpp_side.html
index e0f8f31b..d32f1c7d 100644
--- a/articles/cpp_side.html
+++ b/articles/cpp_side.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/debugging.html b/articles/debugging.html
index 1a7c4938..80291bcc 100644
--- a/articles/debugging.html
+++ b/articles/debugging.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/design_concepts.html b/articles/design_concepts.html
index b5594bb7..0882c30c 100644
--- a/articles/design_concepts.html
+++ b/articles/design_concepts.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/development_patterns.html b/articles/development_patterns.html
index f3e1f09b..b02b5a9c 100644
--- a/articles/development_patterns.html
+++ b/articles/development_patterns.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
@@ -123,7 +123,7 @@ <h3 id="constructing-and-using-objects">Constructing and Using Objects<a class="
 <div class="sourceCode" id="cb3"><pre class="downlit sourceCode r">
 <code class="sourceCode R"><span><span class="va">sir_flows_reader</span> <span class="op">=</span> <span class="fu"><a href="../reference/Reader.html">CSVReader</a></span><span class="op">(</span><span class="va">sir_path</span>, <span class="st">"flows.csv"</span><span class="op">)</span></span>
 <span><span class="va">sir_flows_reader</span></span>
-<span><span class="co">#&gt; Classes 'CSVReader', 'Reader', 'Base' &lt;environment: 0x5587b5d73308&gt; </span></span>
+<span><span class="co">#&gt; Classes 'CSVReader', 'Reader', 'Base' &lt;environment: 0x562e5f28ef68&gt; </span></span>
 <span><span class="co">#&gt; read : function ()  </span></span>
 <span><span class="co">#&gt; read_base : function ()</span></span></code></pre></div>
 <p>We get a print out of the <code>S3</code> class of the object, which
@@ -242,7 +242,7 @@ <h3 id="defining-classes">Defining Classes<a class="anchor" aria-label="anchor"
 <span><span class="op">}</span></span>
 <span><span class="va">does_nothing</span> <span class="op">=</span> <span class="fu">DoesNothing</span><span class="op">(</span><span class="op">)</span></span>
 <span><span class="va">does_nothing</span></span>
-<span><span class="co">#&gt; Classes 'DoesNothing', 'Base' &lt;environment: 0x5587b7320c38&gt;</span></span></code></pre></div>
+<span><span class="co">#&gt; Classes 'DoesNothing', 'Base' &lt;environment: 0x562e608270f8&gt;</span></span></code></pre></div>
 <p>The first line in this constructor uses the <code>Base</code>
 function to create an <code>environment</code> called <code>self</code>.
 The second line sets <code>self</code>s S3 <code>class</code> to
@@ -257,7 +257,7 @@ <h3 id="defining-classes">Defining Classes<a class="anchor" aria-label="anchor"
 <span><span class="op">}</span></span>
 <span><span class="va">does_nothing</span> <span class="op">=</span> <span class="fu">DoesNothing</span><span class="op">(</span><span class="fl">10</span><span class="op">)</span></span>
 <span><span class="va">does_nothing</span></span>
-<span><span class="co">#&gt; Classes 'DoesNothing', 'Base' &lt;environment: 0x5587b759c8b8&gt;</span></span></code></pre></div>
+<span><span class="co">#&gt; Classes 'DoesNothing', 'Base' &lt;environment: 0x562e60aa5690&gt;</span></span></code></pre></div>
 <p>This looks identical to the first version, but now we have stored a
 value for <code>n</code>.</p>
 <div class="sourceCode" id="cb11"><pre class="downlit sourceCode r">
diff --git a/articles/elementwise_binary_operators.html b/articles/elementwise_binary_operators.html
index 8943447a..56e80788 100644
--- a/articles/elementwise_binary_operators.html
+++ b/articles/elementwise_binary_operators.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/engine_agnostic_grammar.html b/articles/engine_agnostic_grammar.html
index b70bd45c..2831dcf0 100644
--- a/articles/engine_agnostic_grammar.html
+++ b/articles/engine_agnostic_grammar.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/example_models.html b/articles/example_models.html
index 9496fc45..8516dd86 100644
--- a/articles/example_models.html
+++ b/articles/example_models.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/index.html b/articles/index.html
index 1f6cd905..5333e232 100644
--- a/articles/index.html
+++ b/articles/index.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/likelihood_prior_specs.html b/articles/likelihood_prior_specs.html
index 6cbd1edb..b4a1b043 100644
--- a/articles/likelihood_prior_specs.html
+++ b/articles/likelihood_prior_specs.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
@@ -227,7 +227,7 @@ <h3 id="priors-on-distributional-parameters">Priors on distributional parameters
 <span><span class="va">cal</span><span class="op">$</span><span class="va">simulator</span><span class="op">$</span><span class="va">tmb_model</span><span class="op">$</span><span class="va">obj_fn</span><span class="op">$</span><span class="va">obj_fn_expr</span></span>
 <span><span class="co">#&gt; ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta, </span></span>
 <span><span class="co">#&gt;     0.35, exp(my_var))) - sum(dnorm(log(my_var), 1, 1))</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x5650ccd59ba0&gt;</span></span>
+<span><span class="co">#&gt; &lt;environment: 0x5639e5f77088&gt;</span></span>
 <span></span>
 <span><span class="fu"><a href="../reference/mp_optimize.html">mp_optimize</a></span><span class="op">(</span><span class="va">cal</span><span class="op">)</span></span>
 <span><span class="co">#&gt; $par</span></span>
diff --git a/articles/quickstart.html b/articles/quickstart.html
index 6b6575de..d1a21dbe 100644
--- a/articles/quickstart.html
+++ b/articles/quickstart.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/real_data.html b/articles/real_data.html
index c9128cab..28945651 100644
--- a/articles/real_data.html
+++ b/articles/real_data.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
@@ -128,21 +128,21 @@ <h2 id="one-scarlet-fever-outbreak-in-ontario">One Scarlet Fever Outbreak in Ont
 <span>  , period_end_date <span class="op">=</span> <span class="st">"1929-08-01..1930-10-01"</span></span>
 <span><span class="op">)</span></span>
 <span><span class="fu"><a href="../reference/engine_functions.html">print</a></span><span class="op">(</span><span class="va">scarlet_fever_ontario</span><span class="op">)</span></span>
-<span><span class="co">#&gt; <span style="color: #949494;"># A tibble: 61 × 18</span></span></span>
-<span><span class="co">#&gt;    basal_disease cases_this_period dataset_id            digitization_id disease</span></span>
-<span><span class="co">#&gt;    <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>                     <span style="color: #949494; font-style: italic;">&lt;dbl&gt;</span> <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>                 <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>           <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>  </span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 1</span> scarlet-fever                23 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 2</span> scarlet-fever                27 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 3</span> scarlet-fever                47 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 4</span> scarlet-fever                24 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 5</span> scarlet-fever                24 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 6</span> scarlet-fever                45 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 7</span> scarlet-fever                57 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 8</span> scarlet-fever                46 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 9</span> scarlet-fever                45 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
-<span><span class="co">#&gt; <span style="color: #BCBCBC;">10</span> scarlet-fever                67 canmod-cdi-harmonized cdi_sf_ca_1924… scarle…</span></span>
+<span><span class="co">#&gt; <span style="color: #949494;"># A tibble: 61 × 19</span></span></span>
+<span><span class="co">#&gt;    basal_disease cases_this_period collection_year dataset_id    digitization_id</span></span>
+<span><span class="co">#&gt;    <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>                     <span style="color: #949494; font-style: italic;">&lt;dbl&gt;</span>           <span style="color: #949494; font-style: italic;">&lt;dbl&gt;</span> <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>         <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>          </span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 1</span> scarlet-fever                23            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 2</span> scarlet-fever                27            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 3</span> scarlet-fever                47            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 4</span> scarlet-fever                24            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 5</span> scarlet-fever                24            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 6</span> scarlet-fever                45            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 7</span> scarlet-fever                57            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 8</span> scarlet-fever                46            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;"> 9</span> scarlet-fever                45            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
+<span><span class="co">#&gt; <span style="color: #BCBCBC;">10</span> scarlet-fever                67            <span style="text-decoration: underline;">1</span>929 canmod-cdi-h… cdi_sf_ca_1924…</span></span>
 <span><span class="co">#&gt; <span style="color: #949494;"># ℹ 51 more rows</span></span></span>
-<span><span class="co">#&gt; <span style="color: #949494;"># ℹ 13 more variables: historical_disease &lt;chr&gt;,</span></span></span>
+<span><span class="co">#&gt; <span style="color: #949494;"># ℹ 14 more variables: disease &lt;chr&gt;, historical_disease &lt;chr&gt;,</span></span></span>
 <span><span class="co">#&gt; <span style="color: #949494;">#   historical_disease_family &lt;chr&gt;, historical_disease_subclass &lt;chr&gt;,</span></span></span>
 <span><span class="co">#&gt; <span style="color: #949494;">#   iso_3166 &lt;chr&gt;, iso_3166_2 &lt;chr&gt;, location &lt;chr&gt;, location_type &lt;chr&gt;,</span></span></span>
 <span><span class="co">#&gt; <span style="color: #949494;">#   nesting_disease &lt;chr&gt;, original_dataset_id &lt;chr&gt;, period_end_date &lt;date&gt;,</span></span></span>
diff --git a/articles/state_dependent_rates.html b/articles/state_dependent_rates.html
index 3f471a93..38684bc7 100644
--- a/articles/state_dependent_rates.html
+++ b/articles/state_dependent_rates.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/state_updaters.html b/articles/state_updaters.html
index a03bcdf7..73d7dd58 100644
--- a/articles/state_updaters.html
+++ b/articles/state_updaters.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
@@ -441,7 +441,7 @@ <h3 id="changemodel-classes">
 <div class="sourceCode" id="cb17"><pre class="downlit sourceCode r">
 <code class="sourceCode R"><span><span class="va">si</span> <span class="op">=</span> <span class="fu"><a href="../reference/mp_tmb_library.html">mp_tmb_library</a></span><span class="op">(</span><span class="st">"starter_models"</span>, <span class="st">"sir"</span>, package <span class="op">=</span> <span class="st">"macpan2"</span><span class="op">)</span></span>
 <span><span class="va">si</span><span class="op">$</span><span class="va">change_model</span></span>
-<span><span class="co">#&gt; Classes 'SimpleChangeModel', 'ChangeModelDefaults', 'ChangeModel', 'Base' &lt;environment: 0x555d01240008&gt; </span></span>
+<span><span class="co">#&gt; Classes 'SimpleChangeModel', 'ChangeModelDefaults', 'ChangeModel', 'Base' &lt;environment: 0x55a56aa1d908&gt; </span></span>
 <span><span class="co">#&gt; after_loop : function ()  </span></span>
 <span><span class="co">#&gt; after_state : function ()  </span></span>
 <span><span class="co">#&gt; all_user_aware_names : function ()  </span></span>
@@ -471,26 +471,26 @@ <h3 id="changemodel-classes">
 <span><span class="va">si</span><span class="op">$</span><span class="va">change_model</span><span class="op">$</span><span class="fu">update_state</span><span class="op">(</span><span class="op">)</span></span>
 <span><span class="co">#&gt; [[1]]</span></span>
 <span><span class="co">#&gt; S ~ -infection</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x555d0064f388&gt;</span></span>
+<span><span class="co">#&gt; &lt;environment: 0x55a56a1dde20&gt;</span></span>
 <span><span class="co">#&gt; </span></span>
 <span><span class="co">#&gt; [[2]]</span></span>
 <span><span class="co">#&gt; I ~ +infection - recovery</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x555d0064f388&gt;</span></span>
+<span><span class="co">#&gt; &lt;environment: 0x55a56a1dde20&gt;</span></span>
 <span><span class="co">#&gt; </span></span>
 <span><span class="co">#&gt; [[3]]</span></span>
 <span><span class="co">#&gt; R ~ +recovery</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x555d0064f388&gt;</span></span>
+<span><span class="co">#&gt; &lt;environment: 0x55a56a1dde20&gt;</span></span>
 <span><span class="va">si</span><span class="op">$</span><span class="va">change_model</span><span class="op">$</span><span class="fu">update_flows</span><span class="op">(</span><span class="op">)</span></span>
 <span><span class="co">#&gt; $S</span></span>
 <span><span class="co">#&gt; $S[[1]]</span></span>
 <span><span class="co">#&gt; infection ~ I * beta/N</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x555d007014d0&gt;</span></span>
+<span><span class="co">#&gt; &lt;environment: 0x55a56a06efc0&gt;</span></span>
 <span><span class="co">#&gt; </span></span>
 <span><span class="co">#&gt; </span></span>
 <span><span class="co">#&gt; $I</span></span>
 <span><span class="co">#&gt; $I[[1]]</span></span>
 <span><span class="co">#&gt; recovery ~ gamma</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x555d007014d0&gt;</span></span></code></pre></div>
+<span><span class="co">#&gt; &lt;environment: 0x55a56a06efc0&gt;</span></span></code></pre></div>
 <div class="sourceCode" id="cb18"><pre class="downlit sourceCode r">
 <code class="sourceCode R"><span><span class="va">spec</span> <span class="op">=</span> <span class="fu"><a href="../reference/mp_tmb_model_spec.html">mp_tmb_model_spec</a></span><span class="op">(</span></span>
 <span>  during <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span></span>
@@ -502,13 +502,13 @@ <h3 id="changemodel-classes">
 <span><span class="co">#&gt; $A</span></span>
 <span><span class="co">#&gt; $A[[1]]</span></span>
 <span><span class="co">#&gt; r ~ a</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x555cf7fc4328&gt;</span></span>
+<span><span class="co">#&gt; &lt;environment: 0x55a569956fc0&gt;</span></span>
 <span><span class="co">#&gt; </span></span>
 <span><span class="co">#&gt; </span></span>
 <span><span class="co">#&gt; $B</span></span>
 <span><span class="co">#&gt; $B[[1]]</span></span>
 <span><span class="co">#&gt; rr ~ b</span></span>
-<span><span class="co">#&gt; &lt;environment: 0x555cf7fc4328&gt;</span></span></code></pre></div>
+<span><span class="co">#&gt; &lt;environment: 0x55a569956fc0&gt;</span></span></code></pre></div>
 </div>
 <div class="section level3">
 <h3 id="updatemethod-classes">
diff --git a/articles/time_varying_parameters.html b/articles/time_varying_parameters.html
index 4695c202..28b68a15 100644
--- a/articles/time_varying_parameters.html
+++ b/articles/time_varying_parameters.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/time_varying_parameters_advanced.html b/articles/time_varying_parameters_advanced.html
index c533cb50..3453413d 100644
--- a/articles/time_varying_parameters_advanced.html
+++ b/articles/time_varying_parameters_advanced.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/articles/vignette_status.html b/articles/vignette_status.html
index dde19421..543eb62c 100644
--- a/articles/vignette_status.html
+++ b/articles/vignette_status.html
@@ -20,7 +20,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/authors.html b/authors.html
index fa51bb23..1b705d77 100644
--- a/authors.html
+++ b/authors.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
@@ -81,13 +81,13 @@ <h2 id="citation">Citation</h2>
 
       <p>Steve Walker, Weiguang Guan, Jen Freeman, Ben Bolker, Darren Flynn-Primrose (2024).
 <em>macpan2: Fast and Flexible Compartmental Modelling</em>.
-R package version 1.11.0, https://github.com/canmod/macpan2, <a href="https://canmod.github.io/macpan2/">https://canmod.github.io/macpan2/</a>.
+R package version 1.11.1, https://github.com/canmod/macpan2, <a href="https://canmod.github.io/macpan2/">https://canmod.github.io/macpan2/</a>.
 </p>
       <pre>@Manual{,
   title = {macpan2: Fast and Flexible Compartmental Modelling},
   author = {{Steve Walker} and {Weiguang Guan} and {Jen Freeman} and {Ben Bolker} and {Darren Flynn-Primrose}},
   year = {2024},
-  note = {R package version 1.11.0, https://github.com/canmod/macpan2},
+  note = {R package version 1.11.1, https://github.com/canmod/macpan2},
   url = {https://canmod.github.io/macpan2/},
 }</pre>
     </div>
diff --git a/index.html b/index.html
index 2d41958b..a6fcf573 100644
--- a/index.html
+++ b/index.html
@@ -22,7 +22,7 @@
 
     <a class="navbar-brand me-2" href="index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/news/index.html b/news/index.html
index 75f18b1d..5345d91a 100644
--- a/news/index.html
+++ b/news/index.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/pkgdown.yml b/pkgdown.yml
index ec64c5bd..53b3bb25 100644
--- a/pkgdown.yml
+++ b/pkgdown.yml
@@ -21,7 +21,7 @@ articles:
   time_varying_parameters_advanced: time_varying_parameters_advanced.html
   time_varying_parameters: time_varying_parameters.html
   vignette_status: vignette_status.html
-last_built: 2024-11-06T19:37Z
+last_built: 2024-11-15T19:28Z
 urls:
   reference: https://canmod.github.io/macpan2/reference
   article: https://canmod.github.io/macpan2/articles
diff --git a/reference/.macpan/default/log.txt b/reference/.macpan/default/log.txt
new file mode 100644
index 00000000..acf8e169
--- /dev/null
+++ b/reference/.macpan/default/log.txt
@@ -0,0 +1,6 @@
+======== macpan2 log file ========
+Error code = 0
+Error message = OK
+Expression row = 0
+Function code = -99
+Time step = 0
diff --git a/reference/BinaryOperator.html b/reference/BinaryOperator.html
index aea5515a..cb92dbcb 100644
--- a/reference/BinaryOperator.html
+++ b/reference/BinaryOperator.html
@@ -19,7 +19,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/LedgerDefinition.html b/reference/LedgerDefinition.html
index ed3fcba2..6f06f793 100644
--- a/reference/LedgerDefinition.html
+++ b/reference/LedgerDefinition.html
@@ -41,7 +41,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/Reader.html b/reference/Reader.html
index 6189c66c..e076e6e6 100644
--- a/reference/Reader.html
+++ b/reference/Reader.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/StringData.html b/reference/StringData.html
index da07c7a1..22f1b62c 100644
--- a/reference/StringData.html
+++ b/reference/StringData.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/Transform.html b/reference/Transform.html
index 6ad3162c..747cb68e 100644
--- a/reference/Transform.html
+++ b/reference/Transform.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/comparison.html b/reference/comparison.html
index ebf2ad01..3359d5dc 100644
--- a/reference/comparison.html
+++ b/reference/comparison.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/distribution.html b/reference/distribution.html
index c60694bb..108dad54 100644
--- a/reference/distribution.html
+++ b/reference/distribution.html
@@ -59,7 +59,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/empty_matrix.html b/reference/empty_matrix.html
index ca1c0fa2..34ffd2d9 100644
--- a/reference/empty_matrix.html
+++ b/reference/empty_matrix.html
@@ -13,7 +13,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/engine_eval.html b/reference/engine_eval.html
index b5ffc043..cd939d7a 100644
--- a/reference/engine_eval.html
+++ b/reference/engine_eval.html
@@ -13,7 +13,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/engine_functions.html b/reference/engine_functions.html
index 08435635..83fd32d3 100644
--- a/reference/engine_functions.html
+++ b/reference/engine_functions.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/finalizer.html b/reference/finalizer.html
index eefd032c..5feb30c5 100644
--- a/reference/finalizer.html
+++ b/reference/finalizer.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/find_all_paths.html b/reference/find_all_paths.html
index ab9ecf9c..8ddd9023 100644
--- a/reference/find_all_paths.html
+++ b/reference/find_all_paths.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/fit_distr_params.html b/reference/fit_distr_params.html
index ce65a6b8..79acf718 100644
--- a/reference/fit_distr_params.html
+++ b/reference/fit_distr_params.html
@@ -13,7 +13,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
@@ -112,7 +112,7 @@ <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-e
 <span class="r-in"><span><span class="va">cal</span><span class="op">$</span><span class="va">simulator</span><span class="op">$</span><span class="va">tmb_model</span><span class="op">$</span><span class="va">obj_fn</span><span class="op">$</span><span class="va">obj_fn_expr</span></span></span>
 <span class="r-out co"><span class="r-pr">#&gt;</span> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta, </span>
 <span class="r-out co"><span class="r-pr">#&gt;</span>     0.35, exp(distr_params_log_sd_beta)))</span>
-<span class="r-out co"><span class="r-pr">#&gt;</span> &lt;environment: 0x55f2f1578958&gt;</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> &lt;environment: 0x55c0fbdb67d0&gt;</span>
 <span class="r-in"><span></span></span>
 <span class="r-in"><span><span class="co"># Next we optimize and view the fitted parameters. We can see the </span></span></span>
 <span class="r-in"><span><span class="co"># distributional parameter in the coefficient table with a default value </span></span></span>
@@ -175,7 +175,7 @@ <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-e
 <span class="r-in"><span><span class="va">cal</span><span class="op">$</span><span class="va">simulator</span><span class="op">$</span><span class="va">tmb_model</span><span class="op">$</span><span class="va">obj_fn</span><span class="op">$</span><span class="va">obj_fn_expr</span></span></span>
 <span class="r-out co"><span class="r-pr">#&gt;</span> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta, </span>
 <span class="r-out co"><span class="r-pr">#&gt;</span>     0.35, exp(sd_var)))</span>
-<span class="r-out co"><span class="r-pr">#&gt;</span> &lt;environment: 0x55f2f0b13b60&gt;</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> &lt;environment: 0x55c0fb9bfd58&gt;</span>
 <span class="r-in"><span><span class="fu"><a href="mp_optimize.html">mp_optimize</a></span><span class="op">(</span><span class="va">cal</span><span class="op">)</span></span></span>
 <span class="r-out co"><span class="r-pr">#&gt;</span> outer mgc:  389.7016 </span>
 <span class="r-out co"><span class="r-pr">#&gt;</span> outer mgc:  258.9379 </span>
diff --git a/reference/index.html b/reference/index.html
index 37e2cb1c..f3630a72 100644
--- a/reference/index.html
+++ b/reference/index.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/initial_valid_vars.html b/reference/initial_valid_vars.html
index 57ef34cf..abfca95b 100644
--- a/reference/initial_valid_vars.html
+++ b/reference/initial_valid_vars.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/macpan2-package.html b/reference/macpan2-package.html
index 69349322..8c8ef77a 100644
--- a/reference/macpan2-package.html
+++ b/reference/macpan2-package.html
@@ -13,7 +13,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/make_expr_parser.html b/reference/make_expr_parser.html
index 6b3458cc..4e136068 100644
--- a/reference/make_expr_parser.html
+++ b/reference/make_expr_parser.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_aggregate.html b/reference/mp_aggregate.html
index 8f9c5435..73c393fa 100644
--- a/reference/mp_aggregate.html
+++ b/reference/mp_aggregate.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_cartesian.html b/reference/mp_cartesian.html
index 76e35fca..60800f8f 100644
--- a/reference/mp_cartesian.html
+++ b/reference/mp_cartesian.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_default.html b/reference/mp_default.html
index 405b4d30..348da77a 100644
--- a/reference/mp_default.html
+++ b/reference/mp_default.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_dynamic_model.html b/reference/mp_dynamic_model.html
index d734efee..7102a90c 100644
--- a/reference/mp_dynamic_model.html
+++ b/reference/mp_dynamic_model.html
@@ -15,7 +15,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_dynamic_simulator.html b/reference/mp_dynamic_simulator.html
index 37f2cb09..119b5a00 100644
--- a/reference/mp_dynamic_simulator.html
+++ b/reference/mp_dynamic_simulator.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_effects_descr.html b/reference/mp_effects_descr.html
index 9f60e63e..1d7a0549 100644
--- a/reference/mp_effects_descr.html
+++ b/reference/mp_effects_descr.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_euler.html b/reference/mp_euler.html
index ed130b51..6cc5d1f1 100644
--- a/reference/mp_euler.html
+++ b/reference/mp_euler.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_expand.html b/reference/mp_expand.html
index fcc2515a..dfa02789 100644
--- a/reference/mp_expand.html
+++ b/reference/mp_expand.html
@@ -19,7 +19,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_extract.html b/reference/mp_extract.html
index 07703fff..863869ce 100644
--- a/reference/mp_extract.html
+++ b/reference/mp_extract.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_factors.html b/reference/mp_factors.html
index 9db27106..c44f4d0f 100644
--- a/reference/mp_factors.html
+++ b/reference/mp_factors.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_final.html b/reference/mp_final.html
index 2fb939e2..a4a0e525 100644
--- a/reference/mp_final.html
+++ b/reference/mp_final.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_flow_frame.html b/reference/mp_flow_frame.html
index 29a52e81..c5139080 100644
--- a/reference/mp_flow_frame.html
+++ b/reference/mp_flow_frame.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_group.html b/reference/mp_group.html
index 58ae3e99..cccfea26 100644
--- a/reference/mp_group.html
+++ b/reference/mp_group.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_index.html b/reference/mp_index.html
index 33ff54cd..949fb5f0 100644
--- a/reference/mp_index.html
+++ b/reference/mp_index.html
@@ -15,7 +15,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_initial.html b/reference/mp_initial.html
index f77e9cd3..7f482259 100644
--- a/reference/mp_initial.html
+++ b/reference/mp_initial.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_join.html b/reference/mp_join.html
index c0f4ddfb..21d9be3f 100644
--- a/reference/mp_join.html
+++ b/reference/mp_join.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_labels.html b/reference/mp_labels.html
index 30c68164..7f85bf12 100644
--- a/reference/mp_labels.html
+++ b/reference/mp_labels.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_layout_grid.html b/reference/mp_layout_grid.html
index 8d064282..1653b745 100644
--- a/reference/mp_layout_grid.html
+++ b/reference/mp_layout_grid.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_layout_paths.html b/reference/mp_layout_paths.html
index f2aaf001..9f2b85d4 100644
--- a/reference/mp_layout_paths.html
+++ b/reference/mp_layout_paths.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_ledgers.html b/reference/mp_ledgers.html
index 289929da..9f79dca5 100644
--- a/reference/mp_ledgers.html
+++ b/reference/mp_ledgers.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_linear.html b/reference/mp_linear.html
index f884b0b4..37367cea 100644
--- a/reference/mp_linear.html
+++ b/reference/mp_linear.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_lookup.html b/reference/mp_lookup.html
index 6fa66acf..ac7df540 100644
--- a/reference/mp_lookup.html
+++ b/reference/mp_lookup.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_model_starter.html b/reference/mp_model_starter.html
index f3b6d072..6ac869f2 100644
--- a/reference/mp_model_starter.html
+++ b/reference/mp_model_starter.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_optimize.html b/reference/mp_optimize.html
index 912542f6..e5386dd5 100644
--- a/reference/mp_optimize.html
+++ b/reference/mp_optimize.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_optimizer_output.html b/reference/mp_optimizer_output.html
index 81033dff..6f49bc0a 100644
--- a/reference/mp_optimizer_output.html
+++ b/reference/mp_optimizer_output.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_par.html b/reference/mp_par.html
index b4654b94..ed1e8768 100644
--- a/reference/mp_par.html
+++ b/reference/mp_par.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_per_capita_flow.html b/reference/mp_per_capita_flow.html
index 0e966db3..4cce4d10 100644
--- a/reference/mp_per_capita_flow.html
+++ b/reference/mp_per_capita_flow.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_positions.html b/reference/mp_positions.html
index ab9904b8..7117ca62 100644
--- a/reference/mp_positions.html
+++ b/reference/mp_positions.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_rbf.html b/reference/mp_rbf.html
index 0c5763ae..89de2f00 100644
--- a/reference/mp_rbf.html
+++ b/reference/mp_rbf.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_reduce.html b/reference/mp_reduce.html
index 98ff2831..f2a2c661 100644
--- a/reference/mp_reduce.html
+++ b/reference/mp_reduce.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_reference.html b/reference/mp_reference.html
index b7a2a3cb..98819ac5 100644
--- a/reference/mp_reference.html
+++ b/reference/mp_reference.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_rename.html b/reference/mp_rename.html
index 14fb6566..5c8bb302 100644
--- a/reference/mp_rename.html
+++ b/reference/mp_rename.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_sim_bounds.html b/reference/mp_sim_bounds.html
index 635cb9eb..5bb921d7 100644
--- a/reference/mp_sim_bounds.html
+++ b/reference/mp_sim_bounds.html
@@ -27,7 +27,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_simulator.html b/reference/mp_simulator.html
index 0bca0661..9f9cccdc 100644
--- a/reference/mp_simulator.html
+++ b/reference/mp_simulator.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_slices.html b/reference/mp_slices.html
index c5cc3e0a..65c92ae5 100644
--- a/reference/mp_slices.html
+++ b/reference/mp_slices.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_square.html b/reference/mp_square.html
index 65f7e9c4..3abfa16e 100644
--- a/reference/mp_square.html
+++ b/reference/mp_square.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_state_dependence_frame.html b/reference/mp_state_dependence_frame.html
index c1ab36d2..e680e378 100644
--- a/reference/mp_state_dependence_frame.html
+++ b/reference/mp_state_dependence_frame.html
@@ -13,7 +13,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_state_vars.html b/reference/mp_state_vars.html
index 4d24e97b..8564780f 100644
--- a/reference/mp_state_vars.html
+++ b/reference/mp_state_vars.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_structured_vector.html b/reference/mp_structured_vector.html
index 01db398e..80541183 100644
--- a/reference/mp_structured_vector.html
+++ b/reference/mp_structured_vector.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_subset.html b/reference/mp_subset.html
index fa4b8dfc..8af0daca 100644
--- a/reference/mp_subset.html
+++ b/reference/mp_subset.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_symmetric.html b/reference/mp_symmetric.html
index ea2029f9..019391b5 100644
--- a/reference/mp_symmetric.html
+++ b/reference/mp_symmetric.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_time_scale.html b/reference/mp_time_scale.html
index bfeabed6..04b5053f 100644
--- a/reference/mp_time_scale.html
+++ b/reference/mp_time_scale.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb.html b/reference/mp_tmb.html
index a40f7a01..f5849376 100644
--- a/reference/mp_tmb.html
+++ b/reference/mp_tmb.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_calibrator.html b/reference/mp_tmb_calibrator.html
index ccdf7d38..163200d5 100644
--- a/reference/mp_tmb_calibrator.html
+++ b/reference/mp_tmb_calibrator.html
@@ -13,7 +13,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_coef.html b/reference/mp_tmb_coef.html
index 8853fe85..86254278 100644
--- a/reference/mp_tmb_coef.html
+++ b/reference/mp_tmb_coef.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_expr_list.html b/reference/mp_tmb_expr_list.html
index 0ecdab52..fc969032 100644
--- a/reference/mp_tmb_expr_list.html
+++ b/reference/mp_tmb_expr_list.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_fixef_cov.html b/reference/mp_tmb_fixef_cov.html
index 932caf08..e78ef6d7 100644
--- a/reference/mp_tmb_fixef_cov.html
+++ b/reference/mp_tmb_fixef_cov.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_insert.html b/reference/mp_tmb_insert.html
index b2a55813..6d60086f 100644
--- a/reference/mp_tmb_insert.html
+++ b/reference/mp_tmb_insert.html
@@ -27,7 +27,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_insert_reports.html b/reference/mp_tmb_insert_reports.html
index 0403225e..95823202 100644
--- a/reference/mp_tmb_insert_reports.html
+++ b/reference/mp_tmb_insert_reports.html
@@ -17,7 +17,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_library.html b/reference/mp_tmb_library.html
index dde9a0b3..6e58faf3 100644
--- a/reference/mp_tmb_library.html
+++ b/reference/mp_tmb_library.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmb_model_spec.html b/reference/mp_tmb_model_spec.html
index 21264120..eb2ded82 100644
--- a/reference/mp_tmb_model_spec.html
+++ b/reference/mp_tmb_model_spec.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_tmbstan_coef.html b/reference/mp_tmbstan_coef.html
index 4116dc05..3d94c349 100644
--- a/reference/mp_tmbstan_coef.html
+++ b/reference/mp_tmbstan_coef.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_traj.html b/reference/mp_traj.html
index 06d1e26c..528dc592 100644
--- a/reference/mp_traj.html
+++ b/reference/mp_traj.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_trajectory.html b/reference/mp_trajectory.html
index ba42c89b..4ae390e7 100644
--- a/reference/mp_trajectory.html
+++ b/reference/mp_trajectory.html
@@ -11,7 +11,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_triangle.html b/reference/mp_triangle.html
index 059c7a8d..3d0afb29 100644
--- a/reference/mp_triangle.html
+++ b/reference/mp_triangle.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_union.html b/reference/mp_union.html
index 8dcf5d65..a0f326e3 100644
--- a/reference/mp_union.html
+++ b/reference/mp_union.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/mp_zero_vector.html b/reference/mp_zero_vector.html
index f2cdf6e6..4802bdec 100644
--- a/reference/mp_zero_vector.html
+++ b/reference/mp_zero_vector.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/names_and_labels.html b/reference/names_and_labels.html
index 3460fc96..16c69f9f 100644
--- a/reference/names_and_labels.html
+++ b/reference/names_and_labels.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/nlist.html b/reference/nlist.html
index 43dd1412..01affc21 100644
--- a/reference/nlist.html
+++ b/reference/nlist.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/rbf.html b/reference/rbf.html
index 9b3eeaf7..f1b35228 100644
--- a/reference/rbf.html
+++ b/reference/rbf.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/show_models.html b/reference/show_models.html
index e7a6c233..5458e75b 100644
--- a/reference/show_models.html
+++ b/reference/show_models.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/simple_sims.html b/reference/simple_sims.html
index 0547a789..1eff0e08 100644
--- a/reference/simple_sims.html
+++ b/reference/simple_sims.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/to_positions.html b/reference/to_positions.html
index 5c60d0bd..0b30b8c8 100644
--- a/reference/to_positions.html
+++ b/reference/to_positions.html
@@ -9,7 +9,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/to_string.html b/reference/to_string.html
index 79ba04b1..f3aa05bc 100644
--- a/reference/to_string.html
+++ b/reference/to_string.html
@@ -7,7 +7,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/reference/transform_distr_param.html b/reference/transform_distr_param.html
index 5ca9b047..5d5b7572 100644
--- a/reference/transform_distr_param.html
+++ b/reference/transform_distr_param.html
@@ -39,7 +39,7 @@
 
     <a class="navbar-brand me-2" href="../index.html">macpan2</a>
 
-    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.0</small>
+    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.11.1</small>
 
 
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
diff --git a/search.json b/search.json
index 5d93cf0f..bfaf4026 100644
--- a/search.json
+++ b/search.json
@@ -1 +1 @@
-[{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":null,"dir":"","previous_headings":"","what":"Contributing to macpan2","title":"Contributing to macpan2","text":"Thank contributing macpan2. Pull requests issues welcome! Developers can see documentation useful contribute code.","code":""},{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":"developer-installation","dir":"","previous_headings":"","what":"Developer Installation","title":"Contributing to macpan2","text":"Developers contributors clone repository call make command-line top level directory. following make rules available getting control build process.","code":"make quick-install     # for changes that only modify R source make quick-doc-install # for changes that modify R source and roxygen comments make quick-test        # quick-doc-install + run-examples + run-tests make run-examples      # help file checks only (without package rebuild) make run-tests         # run scripts in tests (without package rebuild) make full-install      # for all changes, including changes to C++ source make src-update        # push changes to dev.cpp to macpan2.cpp (see below) make enum-update       # register new C++ engine functions on the R-side make engine-doc-update # generate roxygen comments from comments in dev.cpp make doc-update        # roxygenize make pkg-build         # build the R package make pkg-install       # install the R package from the build make pkg-check         # R package checks"},{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":"c-development","dir":"","previous_headings":"","what":"C++ Development","title":"Contributing to macpan2","text":"R packages compiled code, developers edit source files compiled src directory. macpan2 single file directory called macpan2, generated automatically file misc/dev/dev.cpp. setup allows quicker C++ development cycles, developers can edit misc/dev/dev.cpp use file tests without needing re-install package new source. particular, hello-world example use dev.cpp follows. update src/macpan2 state misc/dev/dev.cpp one may run make src-update. Running misc/dev/dev.cpp print debugging information verbose manner, whereas src/macpan2.cpp . src-update make rule removes #define MP_VERBOSE flag top file.","code":"library(macpan2) macpan2:::dev_compile() ## compile dev.cpp options(macpan2_dll = \"dev\") sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") mp_simulator(sir, time_steps = 100, outputs = \"I\")"},{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":"make-in-windows","dir":"","previous_headings":"","what":"Make in Windows","title":"Contributing to macpan2","text":"Developers using make Windows, encounter following compilation error. resolve , may need pass -Wa,-mbig-obj compiler flag GCC via Makeconf file located R installation directory (typically C/Program Files/R/[version R]/etc/x64). Locate CXXFLAGS macro Makeconf file. look something like following. CXXFLAGS = -O2 -Wall $(DEBUGFLAG) -mfpmath=sse -msse2 -mstackrealign $(LTO) Append -Wa,-mbig-obj flag end line save file. likely need make change using Windows Administrator role. CXXFLAGS = -O2 -Wall $(DEBUGFLAG) -mfpmath=sse -msse2 -mstackrealign $(LTO) -Wa,-mbig-obj now able use make described. Note change might increase compilation time (~2 min) described . nice able set flag globally Windows developers. attempt made update Makefile additional line, CXXFLAGS := $(CXXFLAGS) -Wa,-mbig-obj, suggested , successful.","code":"Fatal error: can't write xxx bytes to section .text of macpan2.o: 'file too big' as: macpan2.o: too many sections"},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"setup-and-example-models-and-data","dir":"Articles","previous_headings":"","what":"Setup and Example Models and Data","title":"FAQs","text":"","code":"library(macpan2) library(ggplot2) library(dplyr) library(broom.mixed) options(macpan2_verbose =  FALSE) library(macpan2) si = mp_tmb_model_spec(     before = S ~ 1 - I   , during = mp_per_capita_flow(         from     = \"S\"         ## compartment from which individuals flow       , to       = \"I\"         ## compartment to which individuals flow       , rate     = \"beta * I\"  ## expression giving _per-capita_ flow rate       , abs_rate = \"infection\" ## name for _absolute_ flow rate = beta * I * S     )   , default = list(I = 0.01, beta = 0.2) ) print(si) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       I          0.01 #>    beta          0.20 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ 1 - I #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I\", abs_rate = \"infection\") library(ggplot2) library(dplyr) example_data = (si  |> mp_simulator(time_steps = 50, outputs = \"infection\")  |> mp_trajectory() ) incidence_example = (example_data  |> mutate(value = 100 * value)  |> pull(value) )"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-is-the-package-called-macpan2","dir":"Articles","previous_headings":"Naming Convensions","what":"Why is the package called macpan2?","title":"FAQs","text":"macpan2 package grew McMasterPandemic project. years people involved project started calling macpan, macpan2 successor. package called macpan.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-do-most-of-the-functions-start-with-mp_","dir":"Articles","previous_headings":"Naming Convensions","what":"Why do most of the functions start with mp_?","title":"FAQs","text":"mp stands mac-pan. idea make easy see scripts functions come macpan2 functions come packages.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-do-some-of-the-functions-start-with-mp_tmb_","dir":"Articles","previous_headings":"Naming Convensions","what":"Why do some of the functions start with mp_tmb_?","title":"FAQs","text":"tmb part refers TMB package, macpan2 built. hope one day use computational engines (e.g., stan), point users able see computational engine used scripts. now tmb computational engine thing indicated mp_tmb_ using function intended specific computations TMB. Functions start mp_tmb_ engine-agnostic able used engine.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-does-mean","dir":"Articles","previous_headings":"Coding Style","what":"What does |> mean?","title":"FAQs","text":"use base R pipe operator throughout examples. Please read link details.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-do-i-see-weird-symbols-at-the-start-of-lines","dir":"Articles","previous_headings":"Coding Style","what":"Why do I see weird symbols at the start of lines?","title":"FAQs","text":"start lines characters many people put end lines, commas, plus signs base R pipe. continuation characters tell R code included expression. prefer put characters start lines makes slightly easier comment lines . Note approach work need wrap continued expressions parentheses. See quickstart guide examples style.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-model-fitting-approach-does-macpan2-use","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"What model fitting approach does macpan2 use?","title":"FAQs","text":"fit models finding values parameters peak posterior distribution. approach sometimes called maximum posteriori (MAP) estimation. approach allows us get approximate Bayesian uncertainty estimates approximating posterior distribution multivariate Gaussian centered peak obtained MAP. One able declare parameters considered random effects, means integrated posterior distribution using Laplace approximation. Using approach allows us reduce dimensionality posterior distribution used MAP optimizing fixed effect parameters. approximate posterior distribution can used obtain confidence / credible intervals continuous function model variables. two main examples follows. Confidence intervals fitted parameters using mp_tmb_coef(., conf.int = TRUE). Confidence intervals fitted trajectories using mp_trajectory_sd() approach computing confidence intervals using Gaussian approximations posterior special case delta method implemented TMB, described . Example calibrations varying levels complexity. Intro calibration using toy data Intro calibration using real scarlet fever data hackers McMaster COVID model Wastewater model COVID SHIVER model COVID SEIR model using toy data","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-likelihood-and-prior-distribution-assumptions-does-macpan2-make","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"What likelihood and prior distribution assumptions does macpan2 make?","title":"FAQs","text":"free declare value model trajectory parameter. Trajectories compared observed data produce likelihood component (e.g., case reports distributed negative binomial distribution dispersion parameter 1) parameters used produce component prior distribution (e.g., transmission rate log normally distributed mean 0.2 standard deviation 1). Available distributional assumptions settings described , inspecting examples linked previous FAQ useful figuring use functionality.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-i-hack-macpan2-to-use-mcmc-esimation","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"Can I hack macpan2 to use MCMC esimation?","title":"FAQs","text":"Yes.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-i-get-a-new-model-specification-with-fitted-parameters-as-defaults-from-a-calibrated-calibrator-object","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"Can I get a new model specification with fitted parameters as defaults, from a calibrated calibrator object?","title":"FAQs","text":"Coming soon!","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-can-i-plot-simulated-trajectories","dir":"Articles","previous_headings":"Plotting Simulated Trajectories","what":"How can I plot simulated trajectories?","title":"FAQs","text":"question answered quickstart guide.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-can-i-plot-a-calibrated-model-with-the-observed-data-used-in-the-calibration","dir":"Articles","previous_headings":"Plotting Simulated Trajectories","what":"How can I plot a calibrated model with the observed data used in the calibration?","title":"FAQs","text":"favourite way .","code":"fitted_data = mp_trajectory(model_calibrator) (observed_data   |> ggplot()   + geom_point(aes(time, value))   + geom_line(aes(time, value), data = fitted_data)   + theme_bw() )"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"should-i-worry-about-nanan-function-evaluation-warnings","dir":"Articles","previous_headings":"Calibration Troubleshooting","what":"Should I worry about NA/NaN function evaluation warnings?","title":"FAQs","text":"optimizer sometimes give warnings like . usually nothing worry , though take note . Typically warning indicates optimizer tried parameter values led objective function (.e., negative log posterior density) non-numeric. Usually, opimizer smart enough (possible) get back track. key thing watch whether optimizer converged, can explored using mp_optimizer_output() function illustrated article.","code":"Warning messages: 1: In (function (start, objective, gradient = NULL, hessian = NULL,  :   NA/NaN function evaluation"},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-should-i-do-if-i-do-not-converge","dir":"Articles","previous_headings":"Calibration Troubleshooting","what":"What should I do if I do not converge?","title":"FAQs","text":"depends reason non-convergence. optimizer tries give information , can get information using mp_optimizer_output().","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-do-i-increase-the-number-of-iterations-that-the-optimizer-takes","dir":"Articles","previous_headings":"Calibration Troubleshooting","what":"How do I increase the number of iterations that the optimizer takes?","title":"FAQs","text":"non-convergence results optimizer reaches maximum number iterations allowed take, can increase number (TODO: show example ). Sometimes however, running iterations can (always) sign much information data model parameters estimated.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-can-i-do-when-my-confidence-intervals-overlap-zero-for-a-parameter-that-should-be-positive","dir":"Articles","previous_headings":"Parameter Estimation and Uncertainty","what":"What can I do when my confidence intervals overlap zero for a parameter that should be positive?","title":"FAQs","text":"use mp_tmb_insert() transform parameters go negative. TODO: link example.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-i-weight-the-importance-of-trajectories-when-fitting-to-more-than-one-of-them","dir":"Articles","previous_headings":"Parameter Estimation and Uncertainty","what":"Can I weight the importance of trajectories when fitting to more than one of them?","title":"FAQs","text":"Yes, recommended deep . TODO: give explanation link example.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-is-the-best-way-for-me-to-keep-my-state-variables-from-going-negative","dir":"Articles","previous_headings":"Dynamical Instabilities","what":"What is the best way for me to keep my state variables from going negative?","title":"FAQs","text":"hazard correction (mp_hazard()) works best experience. TODO: link example.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"my-data-start-mid-epidemic-so-how-do-i-know-what-the-initial-number-of-infectious-individuals-is","dir":"Articles","previous_headings":"Initial Conditions","what":"My data start mid-epidemic so how do I know what the initial number of infectious individuals is?","title":"FAQs","text":"common situation data collection often gets better clear problem. simulating epidemic models requires specifying initial conditions state variables, data . basic idea solving problem fit initial numbers state variables. issues. Let’s get example. manipulate example infection data removing first 25 time steps. first issue set time steps . just keep (.e., 26:50) cheating preserving time start epidemic 25 time steps , real life know information. pretend epidemic started 10 time steps data start.  blank space graph time 1 10 represents period outbreak without data. exact size period crucial, long enough let dynamics model settle become independent initial values state variables. Actually, simple SI model example even ignore start-time issue, just fit initial values number infectious individuals. models many state variables becomes easy specify initial conditions model wouldn’t go naturally, resulting dynamical instability. instability can cause optimization problems optimizer might choose starting conditions lead instabilities therefore bad fits. continue SI model illustrate general idea relative simplicity. key ideas code . express initial number infectious individuals N times logistic function new parameter, logit_prop_I, giving proportion population infectious logit scale. transformation allows us fit logit_prop_I ensuring initial value stays 0 N. use mp_sim_bounds function assert first time step 1 last time step max_time, case 35. give prior distribution logit_prop_I see able fit transmission rate, beta, initial proportion infectious individuals, get reasonable confidence intervals. Note logit_prop_I automatically back-transformed prop_I, functionality can turned setting back_transform = FALSE mp_tmb_coef. plot shows model able fit data without knowing initial number infectious individuals 10  Real data simple, principles help.","code":"start_date_offset = 10 in_progress_epidemic = (example_data   |> filter(time > 25)   |> mutate(         value = rpois(length(value), 100 * value)       , time = start_date_offset + row_number()   ) ) max_time = max(in_progress_epidemic$time) (ggplot()   + geom_point(aes(time, value), data = in_progress_epidemic)   + scale_x_continuous(limits = c(1, max_time))   + theme_bw() ) calibrator = (\"starter_models\"  |> mp_tmb_library(\"si\", package = \"macpan2\")  |> mp_tmb_insert(phase = \"before\"     , expressions = list(I ~ N / (1 + exp(-logit_prop_I)))     , default = list(logit_prop_I = 0)   )  |> mp_tmb_calibrator(       data = in_progress_epidemic     , traj = list(infection = mp_neg_bin(disp = 1))     , par = list(         beta = mp_normal(location = 0.4, sd = 1)       , logit_prop_I = mp_normal(location = 0, sd = 1)     )     , time = mp_sim_bounds(1, max_time, \"steps\")  ) ) mp_optimize(calibrator) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>     params     params  #> 0.09910844 0.55847313  #>  #> $objective #> [1] 38.00748 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 9 #>  #> $evaluations #> function gradient  #>       14       10  #>  #> $message #> [1] \"relative convergence (4)\" cc = mp_tmb_coef(calibrator, conf.int = TRUE) print(cc) #>       term    mat row col default  type   estimate  std.error   conf.low #> 1   params   beta   0   0     0.2 fixed 0.09910844 0.04234644 0.01611094 #> 2 params.1 prop_I   0   0     0.5 fixed 0.63609918 0.42942417 0.04404283 #>   conf.high #> 1 0.1821059 #> 2 0.9851457 fitted_data = mp_trajectory(calibrator) (ggplot()   + geom_point(aes(time, value), data = in_progress_epidemic)   + geom_line(aes(time, value), data = fitted_data)   + theme_bw() )"},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-should-i-account-for-delayed-reporting-as-well-as-under-reporting-in-macpan2","dir":"Articles","previous_headings":"Under Reporting, Delayed Reporting, and Total Reporting","what":"How should I account for delayed reporting as well as under-reporting in macpan2?","title":"FAQs","text":"challenge introduced reporting delays compare simulated incidence values model observed case reports, reporting delay. following toy example shows apparent peak data follows simulations.  comparing simulations observed data, use convolution transform simulated incidence values time series reported cases expected model. Keep reading find specifically done.  Now can now compare observed expected reported cases manner accounts reporting delays.  Now explain expected reported case curve computed. method assume new case waits Gamma-distributed random amount time observed. mean coefficient variation distribution can fitted parameters. COVID-19 pandemic McMaster group found Gamma distribution mean delay 11 days coefficient variation 0.25 reasonable model. following figure illustrates single expected case report computed, case time 26. Gamma distribution delay times represented bars giving probability new case particular time reported time 26, given dashed horizontal line. Note reported number cases roughly near (identical) simulated number cases peak delay distribution. makes sense expect reports now come highest probability time past.  macpan2 typically model doesn’t account delayed reporting want update fitting data. One can use mp_tmb_insert_reports() function purpose.  Note function allows accounting -reporting well, specifying report_prob less 1.","code":"si_with_delays = (si  |> mp_tmb_insert_reports(       incidence_name = \"infection\"     , mean_delay = 11     , cv_delay = 0.25     , report_prob = 0.1     , reports_name = \"reports\"  ) ) (si_with_delays   |> mp_simulator(       time_steps = 50L     , outputs = c(\"infection\", \"reports\")   )   |> mp_trajectory()   |> ggplot()   + geom_line(aes(time, value, colour = matrix))   + theme_bw() ) 16: dist ~ pgamma(1:17, 1/(incidence_cv_delay), incidence_mean_delay * (incidence_cv_delay^2)) 17: delta ~ dist[1:16] - dist[0:15] 18: kernel ~ incidence_report_prob * delta/sum(delta) 19: reported_incidence ~ convolution(incidence, kernel)"},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-are-the-mathematical-details-of-the-euler-multinomial-process-error-model","dir":"Articles","previous_headings":"Stochastic Simulation","what":"What are the mathematical details of the Euler multinomial process error model?","title":"FAQs","text":"Euler-multinomial state update method assumes number individuals move one box another single time-step random non-negative integer, coming particular multinomial distribution now describe. probability staying iith box entire time-step assumed following (TODO: relate Poisson processes). pii=exp(−∑jrij) p_{ii} = \\exp\\left(-\\sum_j r_{ij}\\right) probability assumes rijr_{ij} held constant throughout entire time-step, although can change time-step begins. probability moving box ii box jj one time-step given following. pij=(1−pii)rij∑jrij p_{ij} = (1 - p_{ii}) \\frac{r_{ij}}{\\sum_j r_{ij}} probability just probability staying box ii, 1−pii1 - p_{ii}, specifically going box jj, assumed given expression rij∑jrij\\frac{r_{ij}}{\\sum_j r_{ij}}. Let ρij\\rho_{ij} random number individuals move box ii box jj one time-step. expected value ρij\\rho_{ij} pijxip_{ij} x_i. However, random variables independent events, total number individuals, ∑ixi\\sum_i x_i, remain constant single time-step (least models currently considering). account non-independence, collect ρij\\rho_{ij} associated compartment ii vector ρi\\rho_i. collect similar vector probabilities, pip_i. ρi\\rho_i random draw multinomial distribution xix_i trials probability vector, pip_i. random draws made, state variables can updated time-step follows. xi=xi−∑jρij+∑jρji x_i = x_i - \\sum_j \\rho_{ij} + \\sum_j \\rho_{ji} Note actually need generate values diagonal elements, ρii\\rho_{ii}, cancel update equation. also can ignore ρij\\rho_{ij} rij=0r_{ij} = 0. SIR example particularly simple Euler-binomial distribution branching flows – individuals leave S can go leave can go R. two flows given following distributions. ρSI∼Binomial(S,pSI) \\rho_{SI} \\sim \\text{Binomial}(S, p_{SI}) ρIR∼Binomial(,pIR) \\rho_{IR} \\sim \\text{Binomial}(, p_{IR}) models branching flows multinomial distributions. model state update given following equations. S=S−ρSI S = S - \\rho_{SI} =−ρIR+ρSI = - \\rho_{IR} + \\rho_{SI} R=R+ρIR R = R + \\rho_{IR}","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-macpan2-do-the-gillespie-algorithm","dir":"Articles","previous_headings":"Stochastic Simulation","what":"Can macpan2 do the Gillespie algorithm","title":"FAQs","text":". least without substantial hacking. Euler Multinomial used instead","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"more-process-error-incomplete","dir":"Articles","previous_headings":"Stochastic Simulation","what":"More Process Error (incomplete)","title":"FAQs","text":"","code":"set.seed(1L) spec = mp_tmb_model_spec(     before = list(         R ~ vaxprop * N       , S ~ N - I - R     )   , during = list(         infection ~ reulermultinom(S, beta * I / N)       , recovery ~ reulermultinom(I, gamma)       , S ~ S - infection       , I ~ I + infection - recovery       , R ~ R + recovery     )   , default = list(         vaxprop = 0.71111111       , N = 1000       , I = 10       , beta = 1.25       , gamma = 1.1     ) ) (spec   |> mp_simulator(       time_steps = 10     , outputs = \"infection\"   )    |> mp_trajectory_replicate(1L) ) #> [[1]] #>       matrix time row col value #> 1  infection    1   0   0     2 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     1 #> 4  infection    4   0   0     3 #> 5  infection    5   0   0     2 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 vaxprop = 0.7 N = 1000 set.seed(10) spec = mp_tmb_model_spec(     before = list(S ~ N - I - R)   , during = list(         infection ~ reulermultinom(S, beta * I / N)       , recovery ~ reulermultinom(I, gamma)       , S ~ S - infection       , I ~ I + infection - recovery       , R ~ R + recovery     )   , default = list(         N = N       , R = round(vaxprop * N)       , I = 10       , beta = 1.25       , gamma = 1.1     ) ) sim = (spec   |> mp_simulator(       time_steps = 10     , outputs = \"infection\"   ) ) sim |> mp_trajectory_replicate(10) #> [[1]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[2]] #>       matrix time row col value #> 1  infection    1   0   0     4 #> 2  infection    2   0   0     3 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[3]] #>       matrix time row col value #> 1  infection    1   0   0     1 #> 2  infection    2   0   0     1 #> 3  infection    3   0   0     2 #> 4  infection    4   0   0     2 #> 5  infection    5   0   0     1 #> 6  infection    6   0   0     1 #> 7  infection    7   0   0     1 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[4]] #>       matrix time row col value #> 1  infection    1   0   0     2 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     3 #> 4  infection    4   0   0     3 #> 5  infection    5   0   0     1 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[5]] #>       matrix time row col value #> 1  infection    1   0   0     0 #> 2  infection    2   0   0     0 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[6]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[7]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     4 #> 3  infection    3   0   0     3 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[8]] #>       matrix time row col value #> 1  infection    1   0   0     4 #> 2  infection    2   0   0     0 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[9]] #>       matrix time row col value #> 1  infection    1   0   0     6 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     1 #> 4  infection    4   0   0     1 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[10]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     3 #> 3  infection    3   0   0     1 #> 4  infection    4   0   0     1 #> 5  infection    5   0   0     1 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 proc_err = rnorm(50) spec = mp_tmb_model_spec(     before = list(S ~ N - I - R)   , during = list(         mean_foi ~ beta * I / N       , mean_infection ~ mean_foi * S       , dev_foi ~ exp(proc_err[time_step(1)])       , mp_per_capita_flow(\"S\", \"I\", \"dev_foi * mean_foi\", \"infection\")       , mp_per_capita_flow(\"I\", \"R\", \"gamma\", \"recovery\")     )   , default = list(         N = N       , R = 0       , I = 1       , beta = 0.4       , gamma = 0.2       , proc_err = proc_err     ) ) sim = (spec |> mp_hazard()   |> mp_simulator(       time_steps = 50     , outputs = \"infection\"   ) ) sim_infection = (sim   |> mp_trajectory()   |> mutate(value = rpois(length(value), value)) ) fixef = list(     beta = mp_log_normal(location = 0.2, sd = 1)   , gamma = mp_log_normal(location = 0.2, sd = 1) ) ranef = list()   #proc_err = mp_normal(location = 0, sd = 0.1) #) cal = mp_tmb_calibrator(     spec = mp_tmb_update(spec, default = list(beta = 0.2, proc_err = rep(0, 50)))   , data = sim_infection   , traj = list(infection = mp_neg_bin(disp = 1))   , par = fixef # mp_par(param = fixef, random = ranef)   , outputs = \"mean_infection\" ) mp_optimize(cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>    params    params  #> 0.5811725 0.2381576  #>  #> $objective #> [1] 215.4921 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 10 #>  #> $evaluations #> function gradient  #>       13       11  #>  #> $message #> [1] \"relative convergence (4)\" mp_tmb_coef(cal) #>       term   mat row col default  type  estimate  std.error #> 1   params  beta   0   0     0.2 fixed 0.5811725 0.03470795 #> 2 params.1 gamma   0   0     0.2 fixed 0.2381576 0.04467113 fit_infection = mp_trajectory(cal) (ggplot()   + geom_point(aes(time, value), data = sim_infection)   + geom_line(aes(time, value, colour = matrix), data = fit_infection)   + theme_bw() )"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"hello-world","dir":"Articles","previous_headings":"","what":"Hello World","title":"Calibrating Compartmental Models to Data","text":"’ll first thing always trying new fitting procedure: simulate clean, nice data model see can recover something close true parameters.","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-0-set-up-simulator-and-generate-data","dir":"Articles","previous_headings":"Hello World","what":"Step 0: set up simulator and generate ‘data’","title":"Calibrating Compartmental Models to Data","text":"using several different versions SIR model, can derived SIR specification model library. specification derive first version model, use generate synthetic data see optimization can recover parameters use simulating.  Note changed default values can try recover using optimization . make things little challenging add Poisson noise prevalence () value:","code":"sir_spec = mp_tmb_library(\"starter_models\"   , \"sir\"   , package = \"macpan2\" ) print(sir_spec) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 300, R = 100, beta = 0.25, gamma = 0.1) ) sir_results = mp_trajectory(sir_simulator) (sir_results   |> ggplot(aes(time, value, colour = matrix))   + geom_line() ) set.seed(101) sir_prevalence = (sir_results     |> dplyr::select(-c(row, col))     |> filter(matrix == \"I\")     |> rename(true_value = value)     |> mutate(value = rpois(n(), true_value)) ) plot_truth <- ggplot(sir_prevalence, aes(time)) +     geom_point(aes(y = value)) +     geom_line(aes(y = true_value)) print(plot_truth)"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-1-add-calibration-information","dir":"Articles","previous_headings":"Hello World","what":"Step 1: add calibration information","title":"Calibrating Compartmental Models to Data","text":"next step produce object can calibrated optimization. make model need specify trajectory fit (case). also need specify parameters fit. value default list model spec can selected fitting. Note change default value N, leave parameters model spec. difference defaults simulator versus calibrator hope recover using optimization. Note calibrator new expressions deal comparisons data. particular objective function optimize. can sanity check make sure default values give reasonable-looking trajectory.","code":"sir_calibrator = mp_tmb_calibrator(sir_spec   , data = sir_prevalence   , traj = \"I\"   , par = c(\"beta\", \"R\")   , default = list(N = 300) ) print(sir_calibrator) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ S * (I * beta/N) #> 2: recovery ~ I * (gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>  #> --------------------- #> After the simulation loop (t = T + 1): #> --------------------- #> 1: sim_I ~ rbind_time(I, obs_times_I) #>  #> --------------------- #> Objective function: #> --------------------- #> ~-sum(dpois(obs_I, clamp(sim_I))) (sir_calibrator   |> mp_trajectory()  |> ggplot(aes(time, value))   + geom_line() )"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-2-do-the-fit","dir":"Articles","previous_headings":"Hello World","what":"Step 2: do the fit","title":"Calibrating Compartmental Models to Data","text":"fit straightforward. Note mp_optimize function modified sir_calibrator object, now contains new fitted parameter values results optimization.","code":"mp_optimize(sir_calibrator)"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-3-check-the-fit","dir":"Articles","previous_headings":"Hello World","what":"Step 3: check the fit","title":"Calibrating Compartmental Models to Data","text":"can print results optimizer (nlminb case) using mp_optimizer_output function. Always check value convergence code (’s 0, something may gone wrong …). mentioned , best-fit parameters stored internally, can get information using mp_tmb_coef function. (Note get message broom.mixed package, please install . mp_tmb_coef wrapper function). correspond pretty well known true values simulation model. known simulated true value trajectory (black line) fact fall within 95% confidence region (red ribbon).","code":"mp_optimizer_output(sir_calibrator) #> $par #>     params     params  #>  0.2345619 86.7030872  #>  #> $objective #> [1] 248.5816 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 12 #>  #> $evaluations #> function gradient  #>       22       12  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" mp_optimize(sir_calibrator) #> $par #>     params     params  #>  0.2345619 86.7030872  #>  #> $objective #> [1] 248.5816 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 1 #>  #> $evaluations #> function gradient  #>        2        1  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" mp_optimizer_output(sir_calibrator, what=\"all\") #> [[1]] #> [[1]]$par #>     params     params  #>  0.2345619 86.7030872  #>  #> [[1]]$objective #> [1] 248.5816 #>  #> [[1]]$convergence #> [1] 0 #>  #> [[1]]$iterations #> [1] 12 #>  #> [[1]]$evaluations #> function gradient  #>       22       12  #>  #> [[1]]$message #> [1] \"both X-convergence and relative convergence (5)\" #>  #>  #> [[2]] #> [[2]]$par #>     params     params  #>  0.2345619 86.7030872  #>  #> [[2]]$objective #> [1] 248.5816 #>  #> [[2]]$convergence #> [1] 0 #>  #> [[2]]$iterations #> [1] 1 #>  #> [[2]]$evaluations #> function gradient  #>        2        1  #>  #> [[2]]$message #> [1] \"both X-convergence and relative convergence (5)\" sir_estimates = mp_tmb_coef(sir_calibrator, conf.int = TRUE) print(sir_estimates) #>       term  mat row col default  type   estimate   std.error   conf.low #> 1   params beta   0   0     0.2 fixed  0.2345619 0.008739338  0.2174331 #> 2 params.1    R   0   0     0.0 fixed 86.7030872 7.028753743 72.9269830 #>     conf.high #> 1   0.2516906 #> 2 100.4791914 mp_default(sir_simulator) |> filter(matrix %in% sir_estimates$mat) #>   matrix row col  value #> 1      R         100.00 #> 2   beta           0.25 sim_vals <- (sir_calibrator   |> mp_trajectory_sd(conf.int = TRUE)   |> filter(matrix == \"I\") ) (plot_truth    + geom_line(data = sim_vals     , aes(y = value)     , colour = \"red\"   )   + geom_ribbon(data = sim_vals     , aes(ymin = conf.low, ymax = conf.high)     , fill = \"red\"     , alpha = 0.2   ) )"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"statistical-model","dir":"Articles","previous_headings":"","what":"Statistical Model","title":"Calibrating Compartmental Models to Data","text":"specific statistical model used fit data. describe . Let observed simulated trajectories vectors IobsI_\\textrm{obs} IsimI_\\textrm{sim}. II symbol chosen fitted prevalence , trajectory model. example, traj = \"infection\" fitted incidence, infection variable model number new cases every time step. simulated trajectories actually function vector, 𝐛\\mathbf b, default values chose make statistical parameters. Therefore, write simulated trajectory function, Isim(𝐛)I_\\textrm{sim}(\\mathbf b). assume observed trajectory Poisson distributed mean given simulated trajectory. Iobs∼Poisson(Isim(𝐛)) I_{\\textrm{obs}} \\sim \\textrm{Poisson}(I_\\textrm{sim}(\\mathbf b)) Given assumptions choose 𝐛\\mathbf b maximize resulting likelihood function, use functionality TMB package (sometimes tmbstan/rstan packages) statistical inference fitted parameters trajectories. recognize statistical model often overly restrictive. macpan2 package developer interface much flexible, allowing detailed control TMB, tmbstan, rstan. interface allows arbitrary likelihood functions, prior distributions, parameter transformations, flexible parameter time-variation models, random effects . See information, although guides describe developer interface instructions may unclear many readers. plan continue adding interface layers, interface described vignette, macpan2 can exposed users.","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"hello-world-an-easy-calibration-exercise","dir":"Articles","previous_headings":"","what":"‘Hello, World’: an easy (??) calibration exercise","title":"Advanced Calibration","text":"’ll first thing always trying new fitting procedure: simulate clean, nice data model see can recover something close true parameters.","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-0-set-up-simulator-and-generate-data","dir":"Articles","previous_headings":"‘Hello, World’: an easy (??) calibration exercise","what":"Step 0: set up simulator and generate ‘data’","title":"Advanced Calibration","text":"using several different versions SIR model, can derived SIR specification model library. specification derive first version model, use generate synthetic data see optimization can recover parameters use simulating. Add noise prevalence () value:","code":"sir_spec = mp_tmb_library(\"starter_models\"   , \"sir\"   , package = \"macpan2\" ) sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 100, beta = 0.2, gamma = 0.1) ) sir_results = mp_trajectory(sir_simulator) set.seed(101) sir_prevalence = (sir_results     |> dplyr::select(-c(row, col))     |> filter(matrix == \"I\")     |> mutate(obs_val = value + rnorm(n(), sd = 1)) ) gg0 <- ggplot(sir_prevalence, aes(time)) +     geom_point(aes(y = obs_val)) +     geom_line(aes(y = value)) print(gg0)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-1-add-calibration-information","dir":"Articles","previous_headings":"‘Hello, World’: an easy (??) calibration exercise","what":"Step 1: add calibration information","title":"Advanced Calibration","text":"Now ’ll use experimental mk_calibrate() function macpan2helpers package Unlike typical R functions, function modifies sim object place (!!) FIXME: place -- make clone, easy oor sanity check: make sure starting values give reasonable-looking trajectory.  simulated trajectory sensible case - log_beta value way large (set default exp(1)≈{\\exp(1) \\approx} 2.72), know case true value 0.2). Hopefully real system know enough get reasonable order--magnitude starting values. (really knew γ≈0.1\\gamma \\approx 0.1, know starting value log(β)=1\\log(\\beta)=1 correspond ${\\cal R}_0 \\approx 28$, clearly unrealistic infectious diseases … Setting log(β)=0\\log(\\beta)=0 instead gives us trajectory still unrealistic (peak observed prevalence 16.7), least ’s smooth. turns good enough, finding appropriate starting values (based external information trial error) often significant part modeling workflow.  Let’s replace starting value log_beta 0: (proper workflow might prefer go back upstream wherever defined default values, rather resetting value fly …)","code":"macpan2helpers::mk_calibrate(sir_simulator,    data = data.frame(I_obs = sir_prevalence$obs_val),    params = list(beta = 1, I_sd = 1),    transforms = list(beta = \"log\", I_sd = \"log\"),    exprs = list(log_lik ~ dnorm(I_obs, I, I_sd)) ) (sir_simulator   |> mp_trajectory()  |> filter(matrix == \"I\")  |> ggplot(aes(time, value))   + geom_line() ) (sir_simulator$report(c(0,0)) |>  filter(matrix == \"I\") |>  ggplot(aes(time, value)) + geom_line() ) sir_simulator$replace$params(     c(0         , 1         )   , c(\"log_beta\", \"log_I_sd\") )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-2-do-the-fit","dir":"Articles","previous_headings":"‘Hello, World’: an easy (??) calibration exercise","what":"Step 2: do the fit","title":"Advanced Calibration","text":"Print results nlminb - always check value convergence code (’s 0, something may gone wrong …) Back-transform parameters: Get information (little uglier …) correspond true values 0.2, 1, pretty close. fixme: can handle back-transformation/parameter naming nicely? coef(), summary() methods … ?? best-fit parameters stored internally, re-run $report() method get information predicted best-fit trajectory:","code":"fit <- sir_simulator$optimize$nlminb() print(fit) #> $par #>      params      params  #> -1.61413121 -0.07942465  #>  #> $objective #> [1] 133.9514 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 12 #>  #> $evaluations #> function gradient  #>       18       13  #>  #> $message #> [1] \"relative convergence (4)\" exp(fit$par) #>    params    params  #> 0.1990635 0.9236476 coefnames <- function(x) {     x$current$params_frame()$mat } drop_trans <- function(x) gsub(\"(log|logit)_\", \"\", x) ff <- sir_simulator$ad_fun() class(ff) <- \"TMB\" (broom.mixed::tidy(ff, conf.int = TRUE)     |> select(-c(type, std.error))     |> mutate(term = drop_trans(coefnames(sir_simulator)))     |> mutate(across(where(is.numeric), exp))     |> as_tibble() ) #> outer mgc:  1.118671e-09  #> outer mgc:  63.85069  #> outer mgc:  63.73186  #> outer mgc:  0.1998001  #> outer mgc:  0.2002001  #> outer mgc:  145.0178 #> # A tibble: 2 × 4 #>   term  estimate conf.low conf.high #>   <chr>    <dbl>    <dbl>     <dbl> #> 1 beta     0.199    0.198     0.201 #> 2 I_sd     0.924    0.804     1.06 sim_vals <- (sir_simulator   |> mp_trajectory()   |> filter(matrix == \"I\") ) gg0 + geom_line(data = sim_vals, aes(y= value), colour = \"red\")"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"a-slightly-harder-more-realistic-example","dir":"Articles","previous_headings":"","what":"A slightly harder, more realistic example","title":"Advanced Calibration","text":"’ll show alternate choices made. ’ll (1) use real data instead simulated; (2) fit beta gamma, (3) use negative binomial response (needs dispersion parameter I_disp instead standard deviation …) look default parameters? (save typing ’m writing generic function runs model specified set parameters, plots results along data.) fixme: basic plotting functionality macpan2helpers ?  great: helps bump value beta (ℛ0=4\\mathcal{R}_0 = 4):  optimize$nlminb() fails (obscurely) first set starting values, works OK increase beta: fixme: (1) clarify default parameters need transformed (.e. work $replace$params(log(c(1, 0.5, 1)), ...)); (2) save loglik values per point can see original (untransformed) values (1, 0.5, 1) lead infinite log-likelihoods, even think ’re clamping variables … ?? (simulated output doesn’t look crazy …)  fit isn’t perfect, can think number reasons (people complicated; model tracking number current infected children, data numbers children bed; haven’t allowed exposed class …).","code":"library(outbreaks) sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 763, I = 3, beta = 1, gamma = 0.5) ) macpan2helpers::mk_calibrate(sir_simulator   , data = data.frame(I_obs = influenza_england_1978_school$in_bed)   , params = list(beta = 1, gamma = 0.5, I_disp = 1)   , transforms = list(beta = \"log\", gamma = \"log\", I_disp = \"log\")   , exprs = list(log_lik ~ dnbinom(I_obs, I, I_disp)) ) sir_simulator$objective(log(c(1, 0.5, 1))) #> [1] 94.70146 sim_plot <- function(pars = log(c(1, 0.5, 1))) {     predvals <- (sir_simulator$report(pars)         |> filter(matrix == \"I\")         |> select(time, I_obs = value)         |> bind_cols(influenza_england_1978_school)     )     ggplot(predvals, aes(time, I_obs)) + geom_line() +         geom_point(aes(y= in_bed)) +         labs(x=\"time\", y = \"I/'in bed'\") } sim_plot() sim_plot(pars = log(c(2, 0.5, 1))) sir_simulator$replace$params(log(c(2, 0.5, 1)), c(\"log_beta\", \"log_gamma\", \"log_I_disp\")) fit <- sir_simulator$optimize$nlminb() #> outer mgc:  38.61651  #> outer mgc:  16.53627  #> outer mgc:  6.449698  #> outer mgc:  48.42602  #> outer mgc:  33.06605  #> outer mgc:  2.831973  #> outer mgc:  0.6015714  #> outer mgc:  0.009401567  #> outer mgc:  1.102318e-06 sim_plot(pars = fit$par)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"computing-and-plotting-confidence-and-prediction-intervals","dir":"Articles","previous_headings":"A slightly harder, more realistic example","what":"Computing and plotting confidence and prediction intervals","title":"Advanced Calibration","text":"code isn’t horribly complex, hopefully somewhat streamlined/automated future. Computing confidence prediction intervals fairly big subject; see Bolker (2008) chapter 7 introduction issues.  intervals based delta method, approximate (nearly CIs approximations, delta method assumes (1) multivariate normality sampling distribution (2) quadratic approximation nonlinearities model). can see leads negative values within CI range points … confidence intervals, prediction intervals (don’t necessarily expect points lie within envelope); prediction intervals non-Normal errors little bit tricky (maybe something Bolker 2008?), worth right now. can also generate intervals based multivariate normal sampling, relaxes second assumption first. Sometimes calculating standard deviations predictions memory-hungry, show get covariance matrix parameters directly fit (take extra computation).  case delta-method (dotted lines) ensemble CIs (ribbons) different (can see ensemble CIs take care negative values CI); certainly wouldn’t badly misled delta method CIs case. Since running ensemble requires many (typically 500-1000) independent runs $report() method, may want computation parallel. , can use many available tools R, example: (parallel::parApply base R, doParallel/foreach, future/furrr, etc.) small models may take longer copy TMBsimulator object different workers takes run ensemble … can also compute prediction intervals via ensemble, adding appropriate amount negative binomial noise simulation. However, makes sense add observation error time series (one observed time series probably want estimate separate dispersion parameters series), ’ll adapt ensemble code pick values adding noise:  Unsurprisingly, prediction intervals (ribbon) much wider delta-method ensemble-quantile (dashed dotted lines) intervals.","code":"obs <- data.frame(     time = seq(nrow(influenza_england_1978_school))   , value = influenza_england_1978_school$in_bed ) res = (sir_simulator$report_with_sd()   |> mutate(         var = factor(matrix, levels = c(\"S\", \"I\", \"R\"))       , lwr_delta = value - 1.96 * sd       , upr_delta = value + 1.96 * sd     ) ) #> outer mgc:  1.102318e-06  #> outer mgc:  2.135549  #> outer mgc:  2.137124  #> outer mgc:  0.5301401  #> outer mgc:  0.5279329  #> outer mgc:  0.007252414  #> outer mgc:  0.007242536 gg_base <- (res   |> ggplot(aes(x = time, y = value))    + geom_line(aes(colour = var))    + geom_point(data = obs) ) gg_ci1 <- (gg_base    + geom_ribbon(         aes(ymin = lwr_delta, ymax = upr_delta, fill = var)       , alpha = 0.3, colour = NA     ) ) print(gg_ci1) sdr = sir_simulator$sdreport() set.seed(101) nsim <- 1000 par <- fit$par H <- numDeriv::jacobian(sir_simulator$ad_fun()$gr, par) #> outer mgc:  1.102318e-06  #> outer mgc:  0.1175492  #> outer mgc:  0.1175562  #> outer mgc:  0.03944411  #> outer mgc:  0.03943403  #> outer mgc:  0.002035877  #> outer mgc:  0.002034903  #> outer mgc:  0.05877466  #> outer mgc:  0.05877806  #> outer mgc:  0.01971997  #> outer mgc:  0.0197191  #> outer mgc:  0.001017896  #> outer mgc:  0.001017494  #> outer mgc:  0.02938693  #> outer mgc:  0.02938943  #> outer mgc:  0.009859049  #> outer mgc:  0.009860486  #> outer mgc:  0.000508977  #> outer mgc:  0.0005087181  #> outer mgc:  0.01469295  #> outer mgc:  0.01469523  #> outer mgc:  0.004928877  #> outer mgc:  0.00493089  #> outer mgc:  0.0002545353  #> outer mgc:  0.0002543122 ## FIXME: why doesn't this match? ## H0 <- with(sir_simulator$ad_fun(), optimHess(par, fn = fn, gr = gr)) Sigma <- solve(H) stopifnot(all.equal(Sigma, unname(sdr$cov.fixed), tolerance = 1e-5)) ## sample from (assumed) multivariate normal distribution of parameters parvals <- MASS::mvrnorm(nsim, mu = par, Sigma = Sigma) ## simulate for each parameter set sim_ensemble <- apply(parvals, 1, function(p) sir_simulator$report(p, .phases = \"during\")$value) ## 42 x 1000 ## compute 95% quantiles across runs (pointwise) mk_quantiles <- function(ensemble, suffix = \"ens\", level = 0.95) {     sim_quantiles <- (t(apply(ensemble, 1, quantile, c((1-level)/2, (1+level)/2)))         |> as.data.frame()         |> setNames(sprintf(c(\"lwr_%s\", \"upr_%s\"),  suffix))     ) } ## attach to existing data res2 <- cbind(res, mk_quantiles(sim_ensemble)) ## plot gg_ci2 <- (gg_base %+% res2) +     geom_ribbon(aes(ymin = lwr_delta, ymax = upr_delta, colour = var), lty = 2, fill = NA) +     geom_ribbon(aes(ymin = lwr_ens, ymax = upr_ens, fill = var), colour = NA, alpha = 0.3) print(gg_ci2) library(parallel) ncores <- max(1, getOption(\"ncores\", round(detectCores()/2))) cl <- makeCluster(ncores) clusterExport(cl = cl, \"sir_simulator\") ## may take a little while sim2 <- parApply(cl = cl,                  parvals, 1,                  function(p) sir_simulator$report(p, .phases = \"during\")$value) stopCluster(cl) stopifnot(all.equal(sim_ensemble, sim2)) ## identical ## negative binomial dispersion ('size') parameter ## (should be able to do this more nicely with a coef() method ... nb_disp <- exp(fit$par[3])   sim_ensemble2 <- apply(parvals, 1,                        function(p) {                            ## FIXME: misspelling '.phases' gives a 'wrong parameter length arg                            s <- sir_simulator$report(p, .phases = \"during\")                            v <- s$value[s$matrix == \"I\"]                            ## force mean to be non-negative                            ## we could also accept the warnings/NA values from negative predictions                            rnbinom(length(v), mu = pmax(0, v), size = nb_disp)                        }) I_ens <- data.frame(time = obs$time, var = \"I\", mk_quantiles(sim_ensemble2, suffix = \"predens\")) ## attach to existing data res3 <- full_join(res2,  I_ens, by = c(\"time\", \"var\")) ## plot gg_ci3 <- (gg_base %+% res3) +     geom_ribbon(aes(ymin = lwr_delta, ymax = upr_delta, colour = var), lty = 2, fill = NA) +     geom_ribbon(aes(ymin = lwr_ens, ymax = upr_ens, colour = var), lty = 3, fill = NA) +     geom_ribbon(aes(ymin = lwr_predens, ymax = upr_predens, fill = var), colour = NA, alpha = 0.3) ## suppress warnings about 'no non-missing args' [because we don't have *_predens vars for S and R] suppressWarnings(     print(gg_ci3)     )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"hamiltonian-mc","dir":"Articles","previous_headings":"","what":"Hamiltonian MC","title":"Advanced Calibration","text":"development Since Markov chain Monte Carlo samples wider range parameter space, ’s easier get numerical troubles - especially since haven’t specified prior distributions. can mitigate problems slightly (1) specifying random-number seed (least problems reproducible) (2) specifying starting conditions rather allowing Stan pick random. Starting best-fit parameters works, conservative - ideally want make sure chains start different points. second strategy use best-fit parameters baseline, jitter randomly ±40%. (diagnostics - check divergent transitions, look R̂\\hat R, traceplots, etc etc; see e.g. bayestestR::diagnostic_posterior(), bayeslot::mcmc_rank_overlay(), shinyStan … brief examples .) case MCMC quantile credible intervals (ribbons) pretty close delta-method MVN ensemble CIs (shown dotted lines) …","code":"library(tmbstan) stan1 <- tmbstan(sir_simulator$ad_fun(), seed = 101, init  = \"last.par.best\") #> Warning in tmbstan(sir_simulator$ad_fun(), seed = 101, init = \"last.par.best\"): #> Re-cycling inits to match number of chains init_fun <- function(jitter = 0.4) {     p <- sir_simulator$ad_fun()$env$last.par.best     p * runif(length(p), 1-jitter, 1+jitter) } stan2 <- tmbstan(sir_simulator$ad_fun(), init = init_fun, seed = 101) broom.mixed::tidy(stan2, conf.int = TRUE) #> # A tibble: 3 × 5 #>   term      estimate std.error conf.low conf.high #>   <chr>        <dbl>     <dbl>    <dbl>     <dbl> #> 1 params[1]    0.554    0.0324    0.498     0.627 #> 2 params[2]   -0.750    0.0700   -0.881    -0.613 #> 3 params[3]    2.54     0.558     1.37      3.59 mcmc_pars <- as.data.frame(stan2, pars = \"lp__\", include = FALSE) sim_mcmc <- apply(mcmc_pars, 1, function(p) sir_simulator$report(p, .phases = \"during\")$value) ## 48 x 1000 I_mcmc <- data.frame(time = obs$time, var = \"I\", mk_quantiles(sim_mcmc, suffix = \"mcmc\")) ## attach to existing data res4 <- cbind(res3,  mk_quantiles(sim_mcmc, suffix = \"mcmc\")) gg_ci4 <- (gg_base %+% res4) +     geom_ribbon(aes(ymin = lwr_delta, ymax = upr_delta, colour = var), lty = 2, fill = NA) +     geom_ribbon(aes(ymin = lwr_ens, ymax = upr_ens, colour = var), lty = 3, fill = NA) +     geom_ribbon(aes(ymin = lwr_mcmc, ymax = upr_mcmc, fill = var), colour = NA, alpha = 0.3) ## suppress warnings about 'no non-missing args' [because we don't have *_predens vars for S and R] suppressWarnings(     print(gg_ci4)     )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"alternative-confidence-intervals","dir":"Articles","previous_headings":"","what":"Alternative confidence intervals","title":"Advanced Calibration","text":", can also get likelihood profile CIs …","code":"ff <- sir_simulator$ad_fun() class(ff) <- \"TMB\" (broom.mixed::tidy(ff, conf.int = TRUE, conf.method = \"profile\")     |> select(-c(type, std.error))     |> mutate(term = drop_trans(coefnames(sir_simulator)))     |> mutate(across(where(is.numeric), exp))     |> as_tibble() )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"irregular-data-multiple-data-streams","dir":"Articles","previous_headings":"","what":"Irregular data; multiple data streams","title":"Advanced Calibration","text":"now ’re going revert previous fake/simulated data. ’ll fit infection prevalence number recovered, adding negative binomial observation noise dropping 50% (approximately) observations random  Numbers samples missing observations: fixme: add information original 1978-influenza article probable starting date, duration, natural history? Comparison fitode ? priors/regularization?? (statistical) diagnostics? e.g. compute residuals, plot vs. time vs fitted values, scale-location plot, etc. ? CI stuff: importance sampling, Juul et al. functional ribbons, … simple time-varying parameters fitting multiple data streams (progress) irregularly sampled data (progress) estimate starting values accumulators/differences: prevalence, deaths forecasting/scenarios","code":"sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 100, beta = 0.2, gamma = 0.1) ) ## `.phases = \"during\"` is important so that the number of observations matches the number of time steps sir_results = sir_simulator$report(.phases = \"during\") set.seed(101) subsamp <- function(x, missprob = 0.5) { x[runif(length(x))<missprob] <- NA; x }  sir_simdat <- (sir_results     |> select(time, matrix, value)     |> filter(matrix %in% c(\"I\", \"R\"))     |> pivot_wider(names_from = \"matrix\", values_from = \"value\")     |> mutate(I_obs = subsamp(rnbinom(n(), mu = I, size = 4)),               R_obs = subsamp(rnbinom(n(), mu = R, size = 8)))     |> select(time, I_obs, R_obs) ) ## re-pivot for plotting purposes ... plotdat <- sir_simdat |> pivot_longer(-time, names_to = \"var\", values_to = \"count\") ggplot(plotdat, aes(time, count, colour = var)) + geom_point() +     geom_smooth(method = \"gam\", method.args = list(family = quasipoisson)) #> `geom_smooth()` using formula = 'y ~ s(x, bs = \"cs\")' #> Warning: Removed 91 rows containing non-finite outside the scale range #> (`stat_smooth()`). #> Warning: Removed 91 rows containing missing values or values outside the scale range #> (`geom_point()`). with(sir_simdat, table(I_missing=is.na(I_obs), R_missing=is.na(R_obs))) #>          R_missing #> I_missing FALSE TRUE #>     FALSE    31   23 #>     TRUE     24   22 ## won't work yet ... need more sophisticated obs/sim matching ... # mk_calibrate(sir_simulator, #              data = sir_simdat, #              params = list(beta = 1, gamma = 0.5, I_disp = 1, R_disp = 1), #              transforms = list(beta = \"log\", gamma = \"log\", I_disp = \"log\", R_disp = \"log\"), #              exprs = list(log_lik ~ dnbinom(I_obs, I, I_disp) + #                           dnbinom(R_obs, R, R_disp)) #              )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"hello-world-the-hard-way","dir":"Articles","previous_headings":"","what":"‘Hello, World’ the hard way","title":"Advanced Calibration","text":"section explains going hood macpan2helpers::mk_calibrate()","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-0-recreate-the-simulator","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 0: recreate the simulator","title":"Advanced Calibration","text":"Since trying add matrix simulator twice causes error, ’ll create new instance simulator:","code":"sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 100, beta = 0.2, gamma = 0.1) )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-1-add-observed-data-and-slots-for-history-etc-","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 1: add observed data and slots for history etc.","title":"Advanced Calibration","text":"files model library sufficient define simulator, now need add structure model object can calibration - specifically, whatever observed data want compare , whatever new variables (“matrices”) expressions evaluate compute goodness fit (aka loss function objective function) particular set parameters. TMBSimulator object (.e., sir_simulator example), $add$matrices() method add new variables space object already stored state variables, etc. (use sir_simulator$matrix_names() list existing matrices, although produces long, scary list internal variables macpan2 constructed) Now use $add$matrices() : add observed data declare matrix storing simulation history variables compare observed data declare matrix store log-likelihood specify matrices save /return report fixme: possibly comment added objects -front, definition files … fixme: examples show sir_simulator$print$matrix_dims() point. good /interpret ?","code":"sir_simulator$add$matrices(   ## observed data   I_obs = sir_prevalence$obs_val,   ## simulated trajectory to compare with data   I_sim = empty_matrix,    ## matrix to contain the log likelihood values at each time step   log_lik = empty_matrix,   ## need to save the simulation history of each of these matrices   .mats_to_save = c(\"I_sim\", \"log_lik\"),   .mats_to_return = c(\"I_sim\", \"log_lik\") )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-2-collect-simulated-values","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 2: collect simulated values","title":"Advanced Calibration","text":"Collect simulated values matrices compared data. .= Inf .phase = \"\" indicates expression come end expressions evaluated iteration simulation loop. Like $add$matrices(), $insert$expressions adds components existing TMBSimulator object - case, expressions computed simulation. (example, since set .phase = \"\", expressions computed time step.) fixme: ’s best way handle irregularly sampled data/match timestamps observed data? (, footnote put ‘extra tricks’ section)","code":"sir_simulator$insert$expressions(   I_sim ~ I,   .phase = \"during\",   .at = Inf )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-3-set-up-and-compute-objective-function","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 3: set up and compute objective function","title":"Advanced Calibration","text":"use log (default) Gaussian density observed values mean (.e. predicted) value simulated values (equivalent least-squares estimation, added complication estimate standard deviation explicitly rather computing residuals). Add new parameter (standard deviation observed distribution around predicted values) rbind_time function gathers together full simulation history I_sim matrix binding together rows iteration. Define objective function (almost always sum negative log-likelihoods point):","code":"sir_simulator$add$matrices( I_sd = 1 ) sir_simulator$insert$expressions(   log_lik ~ dnorm(I_obs, I_sim, I_sd),   .phase = \"after\"   ) sir_simulator$replace$obj_fn(~ -sum(log_lik))"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-4-declare-andor-transform-parameters-to-be-optimized-set-starting-values","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 4: declare and/or transform parameters to be optimized, set starting values","title":"Advanced Calibration","text":"postponed defining I_sd model step (fixme: right?), confusing since used objective function. parameters restricted positive, almost always best estimate log scale. ensures values always non-negative (positive unless transformed values negative large enough magnitude exp(x) underflows zero) advantages optimization (fixme: much detail needed ? Shrink scale optimization, make parameter magnitudes ${\\cal O}(1)$, make Wald estimation reliable …) practice often read parameter starting values CSV file (using read.csv base R readr::read_csv() tidyverse), can set data frame fly Using $add_transformations(Log(\"var\")) automatically adds variable called log_var list matrices.","code":"sir_simulator$add$transformations(Log(\"I_sd\")) sir_simulator$add$transformations(Log(\"beta\")) params <- read.delim(sep = \"|\", header = TRUE,                      text = \" mat       | default log_I_sd  | 0 log_beta  | 1 \") sir_simulator$replace$params_frame(params)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-5-do-the-fit","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 5: do the fit","title":"Advanced Calibration","text":"’s always good idea quick sanity checks objective function try optimize: get finite values (reasonable inputs)? changing inputs change returned value? get error messages running objective function, sir_simulator$report() help debug printing expression gave rise errors. sir_simulator$get$initial(<varname>) print initial values used, sir_simulator$current$params_frame() print full parameter data frame. fixme: easier way substitute single parameter value? Way modify starting conditions optimizer fly? (Specifying start argument gives ‘formal argument “start” matched multiple actual arguments’ – “replace present” functionality)","code":"sir_simulator$objective(c(1,1)) #> [1] 776.0665 sir_simulator$objective(c(0,1)) #> [1] 4408.378 fit <- sir_simulator$optimize$nlminb()"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"measles-data-in-progress","dir":"Articles","previous_headings":"","what":"Measles Data – In-Progress","title":"Advanced Calibration","text":"reasonably difficult problem – fit SIR model weekly measles incidence data London UK six decades.  need use slightly extended version SIR specification includes waning immunity. use radial basis functions model time-variation transmission rate. also make variety questionable assumptions (TODO: fix ), point moment just illustrate usage provide proof concept. example simulation model, fitting data.  looks nothing like observed measles series, illustrates ability generate complex incidence patterns present simple SIR model without radial basis functions waning immunity. modify simulation object able fit measles data. optimization takes quite minutes, still doesn’t converge 10000 function evaluations. red data fitted black observed. perfect fit, bad now (TODO: work , without papering real challenges).","code":"measles = read.csv(   file.path(     \"https://raw.githubusercontent.com/davidearn/iidda/master/data\",     \"meas_uk__lon_1944-94_wk/source-data/meas_uk__lon_1944-94_wk.csv\"   ),   comment = \"#\" ) measles$date = as.Date(sprintf(   \"%s-%s-%s\", measles$year, measles$month, measles$day )) plot(measles$date, measles$cases, type = \"l\") sir_waning = mp_tmb_library(\"starter_models\"   , \"sir_waning\"   , package = \"macpan2\" ) d = 100 n = nrow(measles) simulator = (sir_waning   |> mp_simulator(       time_steps = n     , outputs = c(\"S\", \"I\", \"R\", \"infection\")     , default = list(         N = 100000, I = 500       , gamma = 0.2, phi = 0.01       , X = rbf(n, d)       , b = rnorm(d, sd = 0.01)       , eta = empty_matrix     )   ) )      ## radial basis function evaluations simulator$insert$expressions(     eta ~ gamma * exp(X %*% b)   , .phase = \"before\"   , .at = Inf ) simulator$insert$expressions(     beta ~ eta[time_step(1)] / clamp(S/N, 1/100)   , .phase = \"during\"   , .at = 1 ) simulated_incidence = filter(simulator$report(.phases = \"during\"), matrix == \"infection\")$value plot(measles$date, simulated_incidence, type = \"l\", xlab = \"time\") simulator$add$matrices(     reports = measles$cases   , log_lik = empty_matrix   , sim_reports = empty_matrix ) simulator$insert$expressions(     sim_reports ~ rbind_time(infection)   , .phase = \"after\"   , .at = Inf ) simulator$replace$params(   default = c(       c(0.2, 0.01)     , rep(0, d)     , 500   )   , mat = c(       c(\"gamma\", \"phi\")     , rep(\"b\", d)     , \"I\"   )   , row = c(       rep(0, 2L)     , seq_len(d) - 1L     , 0L   ) ) simulator$replace$obj_fn(~ - sum(dpois(reports, sim_reports))) simulator$optimize$nlminb(control = list(eval.max = 10000, iter.max = 10000, trace = 10)) simulator$optimization_history$get()[[3]]  ## the 3 is there because we tried two other times simulated_incidence = filter(simulator$report(.phases = \"during\"), matrix == \"incidence\")$value plot(measles$date, measles$cases, xlab = \"time\", type = \"l\") lines(measles$date, simulated_incidence, col = 2)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"challenging-logistic-variation-in-transmission-rate","dir":"Articles","previous_headings":"","what":"Challenging Logistic Variation in Transmission Rate","title":"Advanced Calibration","text":"consider problem fitting SIR model simulated dataset model, simulations pose challenges fitting machinery. simulation model includes logistically time-varying transmission rate.  Fitting simulation data, manages converge, wrong value.  fit good! Even though fitting extact noiseless data generating model, fit good? find plot likelihood surface arrows representing magnitude direction -hill gradient towards optimum. Notice flat gradient direction along valley containing optimum (0,1)(0, 1). gradient pointing towards valley along . understand .   Explore carefully: fixme: causes spikiness along ridge? Add points optimization attempt stopped? experimental: working DEoptim (haven’t included yet don’t want Suggest: DEoptim … fixme: also add multi-start example (.e. less fancy DEoptim, suitable surfaces like one multimodal smooth (ref. Raue et al. “Lessons Learned Quantitative Dynamical Modeling Systems Biology” 2013)?) fixme: warning $current$params_vector() mutable/unreliable. Extractor $ad_fun()$env$last.par.best (equivalently optim fit)? fixme: add (abbreviated) sessionInfo output? (Package versions?)","code":"sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(       N = 100000, I = 500     , beta = 0.2, gamma = 0.2   ) ) n = 2500 set.seed(1L) simulator = (sir_spec   |> mp_simulator(       time_steps = n     , outputs = c(\"S\", \"I\", \"R\", \"beta\", \"infection\")     , default = list(         N = 100000, I = 500       , beta = 0.2, gamma = 0.2       , X = cbind(1, scale(seq_len(n)))       , b = c(0, 1)       , beta_values = empty_matrix     )   ) ) simulator$insert$expressions(     beta_values ~ 1 / (1 + exp(-X %*% b))   , .phase = \"before\"   , .at = Inf ) simulator$insert$expressions(     beta ~ beta_values[time_step(1)]   , .phase = \"during\"   , .at = 1 ) simulator$replace$params(     default = c(0, 1)   , mat = rep(\"b\", 2)   , row = 0:1 ) set.seed(5L) sims = mp_trajectory(simulator) (sims   |> rename(variable = matrix)   |> ggplot()   + facet_wrap(~ variable, ncol = 1, scales = 'free')   + geom_line(aes(time, value)) ) set.seed(3L) ## different seeds do result in convergence on the correct value reports = filter(sims, matrix == \"infection\")$value simulator$add$matrices(reports = reports, report_sim = empty_matrix) simulator$insert$expressions(     report_sim ~ rbind_time(infection)   , .phase = \"after\"   , .at = Inf ) simulator$replace$obj_fn(~ -sum(dpois(reports, report_sim))) simulator$replace$params(     default = rnorm(2L) ## random starting values for the optimizer   , mat = rep(\"b\", 2)   , row = 0:1 ) simulator$optimize$nlminb() #> outer mgc:  11268970  #> outer mgc:  7215054  #> outer mgc:  3087372  #> outer mgc:  3522804  #> outer mgc:  470268.8  #> outer mgc:  802897.8  #> outer mgc:  133686.6  #> outer mgc:  4449.854  #> outer mgc:  5.260259  #> outer mgc:  7.984454e-06 #> $par #>     params     params  #> -1.0929130  0.1633477  #>  #> $objective #> [1] 326073.6 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 9 #>  #> $evaluations #> function gradient  #>       12       10  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" simulator$current$params_frame() #>   par_id mat row col    default    current #> 1      0   b   0   0 -0.9619334 -1.0929130 #> 2      1   b   1   0 -0.2925257  0.1633477 fitted_incidence = (simulator$current$params_vector()   |> simulator$report()   |> filter(matrix == \"infection\")   |> pull(value) ) plot(reports, type = \"l\") lines(fitted_incidence, col = 2) make_liksurf <- function(lwr = c(-1, 0), upr = c(1, 2),                          n = c(41, 41)) {     lik_surf = expand.grid(         intercept_parameter = seq(from = lwr[1], to = upr[1],                                    length.out = n[1]),         slope_parameter = seq(from = lwr[2], to = upr[2],                               length.out = n[2])     )     gr = t(apply(lik_surf, 1, simulator$gradient))     lik_surf$z = apply(lik_surf, 1, simulator$objective)     gr = 0.1 * gr / max(abs(gr))     lik_surf$gx = gr[,1]     lik_surf$gy = gr[,2]     return(lik_surf) } lik_surf <- make_liksurf() mk_plot <- function(dd, arrows = TRUE, contours = TRUE,                     arrow_len = 0.05,                     cbrks = (1:10)*1e5) {     gg0 <- (ggplot(dd, aes(intercept_parameter, slope_parameter))         + geom_tile(aes(fill = z))         + theme_bw()         + scale_x_continuous(expand = c(0,0))         + scale_y_continuous(expand = c(0,0))         + annotate(geom = \"point\", x = 0, y = 1, colour = \"yellow\", size = 2,                    pch = 16)         + scale_fill_continuous(trans = \"log10\")      )     if (contours) {         gg0 <- gg0 + geom_contour(aes(z = z), colour = \"red\",                                   breaks = cbrks)     }     if (arrows) {         gg0 <- gg0 + geom_segment(                          data = dd[seq(nrow(dd)) %% 5 == 0 , ],                          aes(                              xend = intercept_parameter - gx,                               yend = slope_parameter - gy                          ),                           arrow = arrow(length = unit(arrow_len, \"inches\")),                           colour = 'white'                      )     }     gg0 } print(mk_plot(lik_surf)) lik_surf2 <- make_liksurf(lwr = c(-0.1, 0.9), upr = c(0.1, 1.1)) print(mk_plot(lik_surf2, arrows = FALSE, cbrks = 1e4*(1:10))) make_mat <- function(x) {   with(x, matrix(z, sqrt(length(z)),             dimnames = list(intercept = unique(intercept_parameter),                             slope = unique(slope_parameter)))        ) } library(rgl) z1 <- make_mat(lik_surf) persp3d(as.numeric(rownames(z)), as.numeric(colnames(z)), log10(z),         col = \"gray\") z2 <- make_mat(lik_surf2) persp3d(as.numeric(rownames(z2)), as.numeric(colnames(z2)), log10(z2),         col = \"gray\") library(DEoptim) set.seed(101) fit <- DEoptim(simulator$objective, lower = rep(-10, 2), upper = rep(10, 2)) fitted_incidence = (simulator$ad_fun()$env$last.par.best     |> simulator$report()     |> filter(matrix == \"infection\")     |> pull(value) ) plot(reports, type = \"l\") lines(fitted_incidence, col = 2)"},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"introduction","dir":"Articles","previous_headings":"","what":"Introduction","title":"Composing Related Simulation Models","text":"defining epidemiological model users often want compute quantities summarize . Examples include simple single-number quantities like R0, Gbar, r, well elaborate objects like stable compartment distribution linearized model. Methods computing summaries arbitrary models deep research area, making difficult include general purpose software. However, always (strong?) possible use brute force simulation methods approximating values. simulation approach take McMasterPandemic. approach modify focal model simulations modified model can used approximate summaries focal model. example, one scale population size 1 zeros compartments except one exposed category. Simulations cohort models generate force infection time-series, turns sum finite length time-series approximation R0. Sometimes summaries computed descriptive purposes, focus use semi-automatically refining calibrations. example, calibrations can often improved including prior information model parameters using Bayesian estimation. can easier get prior information summaries like R0 model parameters. case one might want regularize calibrations using priors R0. another example, helps initialize state vector simulation model using eigenvector linearization focal model. eigenvector often interpretable stable compartment distribution, unrealistic model fluctuations near beginning epidemic often minimized. Another use case model composition occurs online forecasting. forecasts made every n days, forecast n-day period. forecasts model can improved. One simple way carry information previous forecasts forward next forecasting model use final value state vector initial value new model. cases, start focal model generate several related models computing summaries like R0, eigenvectors, final state vectors. combine outputs models produce improved calibrations focal model.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"notation-and-theory","dir":"Articles","previous_headings":"","what":"Notation and Theory","title":"Composing Related Simulation Models","text":"developing general modelling software, need general theory assumptions. trajectory model model following. Takes parameter vector, θ\\theta, initial state vector, xx Simulates changes xx, referred trajectories Compares simulations observed time-series, yy Returns objective function measures deviation simulated trajectories observed time-series trajectory model contains two functions. function, g(θ;x)g(\\theta; x), parameter initial state vector, returns final state vector objective function, f(θ;x;y)f(\\theta; x; y) often omit yy notational compactness simply write f(θ;x)f(\\theta; x). One may estimate θ\\theta θ̂\\hat{\\theta} optimizing ff θ\\theta given xx yy. strategy xx must assumed. course user free try jointly calibrate θ\\theta xx. represent approach mathematically assuming θ\\theta can used determine xx. cases xx determined θ\\theta, omit xx write final state vector objective functions g(θ)g(\\theta) f(θ)f(\\theta). practice however, often enough information observed time series take approach. Furthermore, approach can computationally slow. discuss alternatives naive calibration approaches use single trajectory model. alternatives make use compositions combinations several related trajectory models. approaches focal trajectory model, focus inference forecasting. focal model able generate one models can used improve calibrations focal model.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"online-forecasting","dir":"Articles","previous_headings":"","what":"Online Forecasting","title":"Composing Related Simulation Models","text":"Consider sequence trajectory models result following sequence objective functions, f1(θ1;x1),...,fn(θn;xn)f_1(\\theta_1;x_1), ..., f_n(\\theta_n;x_n). simplicity, assume model state space potentially different parameter spaces. Let final state model ii gi(θi;xi)g_i(\\theta_i;x_i). Assume time split n+1n+1 equally-sized adjacent intervals θi\\theta_i calibrated data iith interval model ii used forecast data interval +1i+1. simple mechanism setting initial state vector models =1i = 1 set objective function +1i+1th model fi+1(θi+1;xi+1=gi(θ̂;xi))f_{+1}(\\theta_{+1};x_{+1} = g_i(\\hat{\\theta}_i;x_i)), θ̂\\hat{\\theta}_i calibrated parameter vector model ii. objective function fast evaluate relative objective function needs calibrate initial state vector. procedure work well forecasts sufficiently accurate forecast period. However, can improved upon fitting iith model forecasted data observed, using final state predicted model initial state next forecasting model.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"eigenvector-state-initialization","dir":"Articles","previous_headings":"","what":"Eigenvector State Initialization","title":"Composing Related Simulation Models","text":"previous online forecasting setup consider determine initial state vector, x1x_1, first model. approach achieving initialize state vector using eigenvector linearized version model. construct objective function fitting model assume two trajectory models parameter state space. Let initial state focal model given xx (possibly modified) eigenvector (possibly modified) linearized model given g0(θ)g_0(\\theta). let objective function focal model f(θ;x)f(\\theta;x). avoid needing specify fit reasonable value xx calibration step, one use following modified objective function, h(θ)=f(θ;x=g0(θ))h(\\theta) = f(\\theta;x = g_0(\\theta)). hidden computational difficulty however. McMasterPandemic uses TMB computational engine. TMB uses automatic differentiation efficiently provide gradients objective functions. Optimizers can make use gradients converge fewer iterations. However, TMB return gradients simulations respect parameters. means gradients return TMB f(θ;x=g0(θ))f(\\theta;x = g_0(\\theta)) take account effect θ\\theta xx g0g_0. means optimization using state-initialization approach able utilize TMB’s speed benefits.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"priors-on-r0","dir":"Articles","previous_headings":"","what":"Priors on R0","title":"Composing Related Simulation Models","text":"construct objective function, f(θ)f(\\theta) prior component one needs two related trajectory models, returns scalar-valued function model parameters, θ\\theta. focal model function, g(θ)g(\\theta), returns negative log likelihood cohort model function, h(θ)h(\\theta), approximates R0 returns negative log prior density value overall objective function given f(θ)=g(θ)+h(θ)f(\\theta) = g(\\theta) + h(\\theta), fast evaluate extent gg hh fast evaluate.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"regenerating-versus-reparameterizing-models","dir":"Articles","previous_headings":"","what":"Regenerating Versus Reparameterizing Models","title":"Composing Related Simulation Models","text":"framework can used model important computational reality using TMB, McMasterPandemic. want change initial state vector can either regenerating model new initial state, reparameterizing model changes parameter vector induce changes initial state. TMB, objective functions simulation functions can take one parameter vector. notation, model parameter vector θ\\theta. models require regeneration, f(θ;x)f(\\theta;x), assume xx constant feature model. change xx means recreating model objects including ff gg can much slower reparameterizing model, particularly want iteratively make changes state vector. Models explicit initial state, f(θ)f(\\theta), assume initial state can changed passing different parameter vector, θ\\theta, faster case model objects need iteratively regenerated. use cases , used regeneration approach. can modify use reparameterization.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"prerequisites","dir":"Articles","previous_headings":"","what":"Prerequisites","title":"The C++ Side","text":"document assumes solid understanding template model builder.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"matrices","dir":"Articles","previous_headings":"","what":"Matrices","title":"The C++ Side","text":"list numerical scalars, vectors, matrices passed input variables R C++. Scalars passed 1--1 matrices vectors n--1, numerical variables actually matrices. Treating numerical objects matrices might seem strange, similar R treats numerical objects vectors. way, R matrices vectors dimensions. just extending logic requiring vectors dimensions. restrictive R however allowing multidimensional arrays. Missing values allowed matrix. R side variables associated unique name, C++ side names associated 0-based index. indices spec 0-based. matrices must zero rows columns. matrix either zero rows zero columns empty matrix. Empty matrices allow placeholders matrices defined simulations. matrices passed using DATA_STRUCT(mats) TMB macro, associated C++ struct extracting component matrices index.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"parameters","dir":"Articles","previous_headings":"","what":"Parameters","title":"The C++ Side","text":"Two vectors parameters passed C++. PARAMETER_VECTOR(params) – vector becomes argument objective function, can therefore optimized using non-linear optimizer simulated using MCMC PARAMETER_VECTOR(random) – vector becomes random effects integrated objective function using Laplace approximation values parameter vectors used update certain elements matrix-valued variables within mats. elements updated described R side two data frames one row every matrix element replaced. data frames constructed R passed C++. columns data frame associated params following. DATA_IVECTOR(p_par_id) – indices params vector giving parameter use updating element mats updated DATA_IVECTOR(p_mat_id) – indices mats giving matrices elements replaced parameters DATA_IVECTOR(p_row_id) – indices rows within matrix associated element replaced parameters DATA_IVECTOR(p_col_id) – indices columns within matrix associated element replaced parameters vectors read C++, loop executed rows table replaces associated mats elements params elements. random vector treated similarly params associated data frame describing elements mats replaced. names columns table : DATA_IVECTOR(r_par_id) DATA_IVECTOR(r_mat_id) DATA_IVECTOR(r_row_id) DATA_IVECTOR(r_col_id) implied convention p stands ‘fixed Parameters’ r ‘Random parameters’.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"trajectory-simulation","dir":"Articles","previous_headings":"","what":"Trajectory Simulation","title":"The C++ Side","text":"input matrices mats updated using params random, matrices can modified. refer process modification trajectory simulation. three phases trajectory simulation process. simulation loop simulation loop simulation loop Simulation time measured dimensionless iterations, indexed integer, t, 0 <= t <= T+1, T number iterations loop. value matrix t = 0 value matrix just first iteration simulation loop begins. value matrix 0 < t < T+1 value matrix end tth iteration simulation loop. value matrix t = T+1 value matrix end simulation. time-indexing system used two purposes. optionally return simulation history user matrix modifications depend past values user can opt uses per-matrix basis, specifying two vectors one element per matrix. Equals 0 matrix overwritten simulation iteration, t Equals 1 computed values matrix saved Equals 0 matrix returned R side end simulation Equals 1 otherwise number iterations, T, passed TMB DATA_INTEGER(time_steps).","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"expressions","dir":"Articles","previous_headings":"","what":"Expressions","title":"The C++ Side","text":"mathematical details matrices modified simulation process controlled R side supplying expressions. expression right-hand-side R formula involving following three types objects. Names matrices mats Names functions currently allowed engine Numeric literals (e.g. 3.14) simulation sequential evaluation expressions user-specified order. expression may evaluated one three simulation phases – , , simulation loop. Expressions evaluated simulation loop evaluated , whereas evaluated loop evaluated every iteration. phase expression controlled DATA_IVECTOR(eval_schedule) vector described end section. mathematical expression can used C++ several ways. Information expression used passed C++ using set vectors. vectors length, one element per expression. Index mats identifying matrix produced expression Identifies whether expression evaluated inside SIMULATE macro within TMB value 0 indicates expression evaluated without SIMULATE macro (expect standard case), whereas value 1 indicates evaluation inside SIMULATE macro Note expression evaluated SIMULATE macro returned user mats_return == 1, must also returned within SIMULATE macro Number rows associated expression parse table (see section Parse Tables) expression evaluated order appears vectors. DATA_IVECTOR(eval_schedule) vector gives phase expressions evaluated. vector three elements giving number expressions evaluate , , simulation loop. particular first eval_schedule[0] expressions evaluated simulation loop, next eval_schedule[1] expressions evaluated every iteration simulation loop, next eval_schedule[2] expressions evaluated simulation loop. Inputs invalid sum elements eval_schedule equal number elements expr_output_id, expr_sim_block, expr_num_p_table_rows.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"parse-tables","dir":"Articles","previous_headings":"","what":"Parse Tables","title":"The C++ Side","text":"expression parsed table numbers represents expression can passed C++. row table corresponds step process evaluating expression. steps correspond one three types things, identified column n: function – n > 0 – see section Function Definitions matrix – n == 0 – see section Matrices literal – n == -1 – see section Literals row correspond function, column n gives number arguments function. column, x, gives index looking specific instance three types entities. example, n == 0 x column gives index mats list getting appropriate matrix n == -1 x gives index literals n > 0 x gives index list valid functions. column relevant functions, indicates row table representing first argument function. table processed C++ side recursive function either: rows associated functions: looks valid function list function definitions, recursively calls rows associated matrices: looks returns matrix mats list rows associated literals: looks returns literal list valid literals parse tables expressions concatenated row-wise passed C++ set three vectors equal length. DATA_IVECTOR(p_table_n) DATA_IVECTOR(p_table_x) DATA_IVECTOR(p_table_i) first three vectors correspond n, x, discussed section. expr_num_p_table_rows vector (defined section Expressions) used relate expression set rows concatenated parse table. elements vector contain number parse table rows associated expression. ordering elements consistent ordering concatenation individual parse tables, row indices necessary.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"literals","dir":"Articles","previous_headings":"","what":"Literals","title":"The C++ Side","text":"global list valid literals expressions passed C++ numeric vector, DATA_VECTOR(literals).","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"function-definitions","dir":"Articles","previous_headings":"","what":"Function Definitions","title":"The C++ Side","text":"functions used [Expression] must valid list functions defined C++ side. functions analogues R side make easy possible R users reason expressions. Valid functions take one matrix-valued arguments return single matrix. number arguments need known model defined, functions may optionally require predefined number arguments. Extending functionality engine typically involve simply adding function definitions list valid functions. function definitions following objects available . r – list matrices giving arguments function (e.g. r[0] returns first matrix). index2mats – list integers giving indices identifying matrices mats list (e.g. index2mats[0] returns index first argument). t – Time step hist – list lists matrices giving history simulation (e.g. hist[4][0] returns value first matrix time step 4). n – number arguments. Function definitions grouped types several functions require similar processing. main example element-wise binary operators, including +, *, -, /, ^. functions require pre-processing make sure matrix dimensions two operands compatible compatibility conveniently defined user.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"objective-function","dir":"Articles","previous_headings":"","what":"Objective Function","title":"The C++ Side","text":"return value objective function expression depend values matrices end simulation entire saved simulation history. expression passed parse table. DATA_IVECTOR(o_table_n) DATA_IVECTOR(o_table_x) DATA_IVECTOR(o_table_i) implied convention o ‘Objective function parse table’ p ‘matrix Parse table’.","code":""},{"path":"https://canmod.github.io/macpan2/articles/debugging.html","id":"choosing-a-debugging-technique","dir":"Articles","previous_headings":"","what":"Choosing a Debugging Technique","title":"Debugging","text":"traceback(m = 1) options(error = recover) debug({package-function}) oor_debug$flag({object-method})","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"information-processing","dir":"Articles","previous_headings":"","what":"Information Processing","title":"Design Concepts","text":"Like statistical modelling software, high-level purpose macpan2 process data sources (top-left) results (bottom-left). case macpan2, processing done using compartmental modelling (right). major steps information processing numbered diagram, describe . Information processing begins accessing preparing numerical information various data sources, output standard numerical R objects. Depending nature analysis follow, information include default values parameters (e.g. transmission rate), initial values state variables (e.g. initial number infectious individuals), operational schedules (e.g. timing lockdown events vaccine roll-schedules), data model fitting (e.g. time series hospital utilization). step involve connecting real-time surveillance platforms reading static data files. functionality within macpan2 conducting step – macpan2 try reinvent wheel data access preparation. (2a) model chosen model library read R, optionally updating model structure using engine-agnostic model specification language. (2b) model written scratch using engine-agnostic model specification language. (2c) model written scratch using one engine-specific model specification languages. three alternatives, 2a chosen 2b 2c automatically executed 2b chosen 2c automatic. choice just close (2c) far (2a) actual computation engine want specifying models. several considerations choosing model specification workflow deciding alternative use. matter approaches taken, output step 2 model simulator can used generate modelling outputs like simulated incidence time-series reproduction numbers. Although model simulators come default initial values can used immediately, typically one like modify values without needing edit model specifications step 2. two main use-cases involving numerical modifications model simulators: order formally calibrate model parameters fitting model observed time-series data /modifying default parameter values reflect -scenario. use-cases, model simulator used input another model simulator produced output. model defining numerical initialization steps completed, model outputs produced long-format data frames. Finally model outputs incorporated forecasts, plots, reports, diagnostics using standard tools outside macpan2.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"modularity","dir":"Articles","previous_headings":"","what":"Modularity","title":"Design Concepts","text":"Modularity key principle macpan2 design ways. First, macpan2 meant plug standard R workflows data pre-processing simulation post-processing. little functionality macpan2 configuring data prepared input modelling outputs processed. Instead, macpan2 accepts standard data objects (data frames, matrices, vectors) returns simulations long-format data frames can processed using standard tools like dplyr ggplot2. design principle illustrated architecture diagram blue steps representing standard non-macpan2 workflows red steps representing workflows depend macpan2 data structures objects. challenges building red steps big enough prefer avoid reinventing wheel pre- post-processing. Second, macpan2 uses engine plug-architecture. Models defined engine-agnostic model specification language can rendered particular computational engine multiple computational approaches can used generate modelling outputs single model definition. can useful different model outputs efficient convenient different computational approaches. example, engines TMB capable automatic differentiation great fast optimization parameters computing ℛ0\\mathcal{R}_0 models arbitrary complexity, whereas engines Adaptive Tau better stochastic simulation techniques like Gillespie algorithm. Sometimes engine unable generate particular output sufficient difficulty part user render use-case practically impossible. example, possible conveniently utilize differential equation solvers TMB engine, limiting Euler simple RK4-type solvers. able swap TMB engine one based deSolve (similar package) allow convenient accurate solutions differential equations without leave macpan2. Third, TODO: describe model specification language can used build models modularly (e.g. swap alternative state-updaters discussed also add model structures like age-groups spatial structure simple unstructured model)","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"engine-agnostic-model-specification-language","dir":"Articles","previous_headings":"","what":"Engine-Agnostic Model Specification Language","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"engine-specific-model-specification-languages","dir":"Articles","previous_headings":"","what":"Engine-Specific Model Specification Languages","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"general-dynamic-simulation-with-tmb","dir":"Articles","previous_headings":"","what":"General Dynamic Simulation with TMB","title":"Design Concepts","text":"One can define generic set update steps iterated produce dynamic simulation model TMB, can used generate model simulations. part package general, stable, flexible. also meets many modellers , ability write set transitions/state updates. convenient just like simulate , model library .","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"model-library","dir":"Articles","previous_headings":"","what":"Model Library","title":"Design Concepts","text":"TODO: Reuse tools older concept starter models Establish specification","code":"(\"starter_models\"  |> mp_tmb_library(\"sir\", package = \"macpan2\")  |> mp_simulator(time_steps = 10, outputs = \"I\")  |> mp_trajectory() ) ##    matrix time row col    value ## 1       I    1   0   0 1.098000 ## 2       I    2   0   0 1.205169 ## 3       I    3   0   0 1.322276 ## 4       I    4   0   0 1.450133 ## 5       I    5   0   0 1.589599 ## 6       I    6   0   0 1.741573 ## 7       I    7   0   0 1.906995 ## 8       I    8   0   0 2.086833 ## 9       I    9   0   0 2.282085 ## 10      I   10   0   0 2.493761"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"calibration","dir":"Articles","previous_headings":"","what":"Calibration","title":"Design Concepts","text":"build function, mp_calibrate, takes (1) object simulating model trajectories (2) information calibrating certain quantities model. second type information detailed following sections. output mp_calibrate another object simulating model trajectories contains new default parameter values given fits additional stochasticity resulting parameter estimation uncertainty. big question calibration want engine-agnostic DSL layer, just want make sense engines makes sense? think latter, otherwise making things difficult. can try wise making reusable calibration machinery across engines comes .","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"specifying-data-to-fit","dir":"Articles","previous_headings":"Calibration","what":"Specifying Data to Fit","title":"Design Concepts","text":"data frame (data frames) containing observed (possibly uneven) time series compare model simulations. form data frame take? One option format output mp_trajectory. several benefits. Consistency input output formats, making little easier learn. Easy manipulate output input testing calibration functionality. Possibly simpler argument list mp_calibrate just relate observed data simulated data name, course still need interface distributional assumptions. Naturally handles missing values main disadvantage format differ indexed vectors discussed . disadvantage fixable way convert indexed vector lists ‘long-matrices’ format. Actually yes … totally fine. general design generic S3 method producing ‘long-matrices’ data frame.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"specifying-distributional-assumptions","dir":"Articles","previous_headings":"Calibration","what":"Specifying Distributional Assumptions","title":"Design Concepts","text":"Probably ways depending many different assumptions need made. one extreme every observation gets distribution, easily specified argument mp_calibrate. extreme observation gets distribution (including distributional parameters like spread shape), specified adding additional columns data frame observed values. Designs interfaces use cases somewhere two extremes seem less obvious.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"specifying-parameters-to-fit","dir":"Articles","previous_headings":"Calibration","what":"Specifying Parameters to Fit","title":"Design Concepts","text":"two kinds parameters fit. Existing quantities fitted (e.g. beta, initial number susceptible individuals S). Creating new quantities fitted (e.g. distributional scale parameters declared along distributional asumptions. scale (e.g. log, logit) fit parameters must also specified. new distributional parameters go new indexed vector called something like distributional_parameters. (TODO: general name new parameters part observation model, e.g. convolution kernel parameters).","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"alternative-trajectory-solvers","dir":"Articles","previous_headings":"","what":"Alternative Trajectory Solvers","title":"Design Concepts","text":"Let xx state vector bb vector per-capita flow rates. Let zz yy vectors states – zz (yy) vector length bb containing elements xx associated () state flow. Therefore, iith flow z[]z[] y[]y[] per-capita rate b[]b[]. way think single flow, xix_i state, xjx_j state, bkb_k per-capita flow rate. Inflow: xibkx_i b_k Outflow: xibkx_i b_k Inflow Outflow: $$","code":"outflow ~ group_sums(state * flow_rates, from, state)"},{"path":[]},{"path":[]},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"time-varying-parameters","dir":"Articles","previous_headings":"","what":"Time-Varying Parameters","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"vectors-in-the-tmb-engine","dir":"Articles","previous_headings":"","what":"Vectors in the TMB Engine","title":"Design Concepts","text":"TMB-engine-specific warm-model structure.","code":"state_labels = c(\"S\", \"I\", \"R\") flow = data.frame(     rate = c(\"infection\", \"recovery\")   , from = c(\"S\"        , \"I\"       )   , to   = c(\"I\"        , \"R\"       ) ) sir = mp_tmb_model_spec(     before = list(         state[S] ~ N - 1       , state[I] ~ 1       , state[R] ~ 0     )   , during = list(         flow_rate[infection] ~ beta * state[S] * state[I] / N       , flow_rate[recovery] ~ gamma * state[I]       , state ~ state + group_sums(flow_rate, to, state) - group_sums(flow_rate, from, state)   )   , default = list(       state     = mp_zero_vector(state_labels)     , flow_rate = mp_zero_vector(flow$rate)     , N = 100     , beta = 0.25     , gamma = 0.1   )   , integers = list(        from = mp_positions(flow$from, state_labels)      , to   = mp_positions(flow$to  , state_labels)   ) ) (sir   |> mp_simulator(time_steps = 10, outputs = \"I\")   |> mp_trajectory() ) ##    matrix time row col    value ## 1   state    1   I     1.147500 ## 2   state    2   I     1.316046 ## 3   state    3   I     1.508417 ## 4   state    4   I     1.727685 ## 5   state    5   I     1.977228 ## 6   state    6   I     2.260727 ## 7   state    7   I     2.582154 ## 8   state    8   I     2.945748 ## 9   state    9   I     3.355960 ## 10  state   10   I     3.817384"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"model-structure-and-bookkeeping","dir":"Articles","previous_headings":"","what":"Model Structure and Bookkeeping","title":"Design Concepts","text":"Structured models combinations simpler modular model components. example one might combine SIR model age-group contact model produce age structured model. modular model components called atomic models.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"structure-in-expressions","dir":"Articles","previous_headings":"Model Structure and Bookkeeping","what":"Structure in Expressions","title":"Design Concepts","text":"Models composed expression lists. expression unstructured model can converted structured expression create structured model. example, following unstructured expression defines rate new infections emerge. symbol expression certain type within structured model, type determines gets translated structured expression. simplest structured model one collects S state vector elements S . interpretation S symbols, structured infection expression gets translated internally following. S become symbols extracting subsets state vector. case expression remains scalar expression two scalars obtained extracting subsets state vector. won’t take much imagination think examples multiple paths infection required, therefore single scalar-valued infection expression insufficient. vector-valued expression, example, model expanded state vector tracks geographic location S individuals. example, two patch model east west patch involve four-dimensional state vector following elements: S.east, S.west, .east, .west. case now two scalar-valued infection expressions. two patches fine write scalar-valued infection expressions, patches different types structure (e.g. age groups, symptom status, hospitalization, immunity status, etc …) become crucial software handles bookkeeping internally. see easy can , note two-patch infection expression can powerfully compactly expressed original unstructured expression, infection ~ beta * S * / N, S = c(state[S.east], state[S.west]) = c(state[.east], state[.west]). powerful? separates math dynamic mechanism, infection ~ beta * S * / N, bookkeeping required structured models mechanism applied different model strata. often modellers think. example, might location-structured SIR model need expand age- location-structured. case, infection still process, whereby susceptible individual contacts infectious individual create flow susceptible individuals infectious individuals. math applies strata model. boring necessary part connect math bookkeeping associated model structure, software focus making bookkeeping changes easy possible minimal changes required underlying mathematical expressions. Let’s look examples infection, watch bookkeeping get annoying. age-stratified model two age groups, now get four scalar-valued infection expressions form infection ~ beta * S * / N. first expression young individual infecting old individual, second old individual infecting young individual, etc … Things get worse two age groups two patches. still isn’t bad, just first four expressions east last four west. now let’s introduce two symptom status categories: mild severe. intense. names square brackets get much less clear several ways model gets structured. lack clarity makes difficult see variety model assumptions looking scalar-valued expressions. infection beta vectors depend two age categories two symptom statuses, one location. young people can infect old people (vice versa), mildly infectious people can cause severe infection (vice versa), infectious people east infect people west (vice versa). labels associated two ages, first age mean, relative second age? discover need know look ages associated S states, can see first age category associated susceptible individual second infectious individual. related issue symptom status, expressed differently S individuals structured symptom status. case match second symptom status associated infection beta symptom status states, means first symptom status implicitly refers status newly infected individuals infectious individuals. Another way look last issue boxes play two different roles. first role individual infects S individual, second individual S individual becomes infected. None obvious scalar-valued expressions , difficult imagine clearer way explicitly write expression. approach bookkeeping different way. particular believe constructive approach structure provides comprehensible description, describe next. brief, believe grammar specifying steps associated adding structure can clearer description final structured model.","code":"infection ~ beta * S * I / N infection ~ beta * state[S] * state[I] / N infection[east] ~ beta * state[S.east] * state[I.east] / N infection[west] ~ beta * state[S.west] * state[I.west] / N infection[young.young] ~ beta[young.young] * state[S.young] * state[I.young] / N[young] infection[young.old]   ~ beta[young.old]   * state[S.young] * state[I.old]   / N[old] infection[old.young]   ~ beta[old.young]   * state[S.old]   * state[I.young] / N[young] infection[old.old]     ~ beta[old.old]     * state[S.old]   * state[I.old]   / N[old] infection[young.young.east] ~ beta[young.young.east] * state[S.young.east] * state[I.young.east] / N[young.east] infection[young.old.east]   ~ beta[young.old.east]   * state[S.young.east] * state[I.old.east]   / N[old.east] infection[old.young.east]   ~ beta[old.young.east]   * state[S.old.east]   * state[I.young.east] / N[young.east] infection[old.old.east]     ~ beta[old.old.east]     * state[S.old.east]   * state[I.old.east]   / N[old.east] infection[young.young.west] ~ beta[young.young.west] * state[S.young.west] * state[I.young.west] / N[young.west] infection[young.old.west]   ~ beta[young.old.west]   * state[S.young.west] * state[I.old.west]   / N[old.west] infection[old.young.west]   ~ beta[old.young.west]   * state[S.old.west]   * state[I.young.west] / N[young.west] infection[old.old.west]     ~ beta[old.old.west]     * state[S.old.west]   * state[I.old.west]   / N[old.west] infection[young.young.east.mild.mild]     ~ beta[young.young.east.mild.mild]     * state[S.young.east] * state[I.young.east.mild]   / N[young.east] infection[young.young.east.mild.severe]   ~ beta[young.young.east.mild.severe]   * state[S.young.east] * state[I.young.east.severe] / N[young.east] infection[young.young.east.severe.mild]   ~ beta[young.young.east.severe.mild]   * state[S.young.east] * state[I.young.east.mild]   / N[young.east] infection[young.young.east.severe.severe] ~ beta[young.young.east.severe.severe] * state[S.young.east] * state[I.young.east.severe] / N[young.east] infection[young.old.east.mild.mild]       ~ beta[young.old.east.mild.mild]       * state[S.young.east] * state[I.old.east.mild]     / N[old.east] infection[young.old.east.mild.severe]     ~ beta[young.old.east.mild.severe]     * state[S.young.east] * state[I.old.east.severe]   / N[old.east] infection[young.old.east.severe.mild]     ~ beta[young.old.east.severe.mild]     * state[S.young.east] * state[I.old.east.mild]     / N[old.east] infection[young.old.east.severe.severe]   ~ beta[young.old.east.severe.severe]   * state[S.young.east] * state[I.old.east.severe]   / N[old.east] infection[old.young.east.mild.mild]       ~ beta[old.young.east.mild.mild]       * state[S.old.east]   * state[I.young.east.mild]   / N[young.east] infection[old.young.east.mild.severe]     ~ beta[old.young.east.mild.severe]     * state[S.old.east]   * state[I.young.east.severe] / N[young.east] infection[old.young.east.severe.mild]     ~ beta[old.young.east.severe.mild]     * state[S.old.east]   * state[I.young.east.mild]   / N[young.east] infection[old.young.east.severe.severe]   ~ beta[old.young.east.severe.severe]   * state[S.old.east]   * state[I.young.east.severe] / N[young.east] infection[old.old.east.mild.mild]         ~ beta[old.old.east.mild.mild]         * state[S.old.east]   * state[I.old.east.mild]     / N[old.east] infection[old.old.east.mild.severe]       ~ beta[old.old.east.mild.severe]       * state[S.old.east]   * state[I.old.east.severe]   / N[old.east] infection[old.old.east.severe.mild]       ~ beta[old.old.east.severe.mild]       * state[S.old.east]   * state[I.old.east.mild]     / N[old.east] infection[old.old.east.severe.severe]     ~ beta[old.old.east.severe.severe]     * state[S.old.east]   * state[I.old.east.severe]   / N[old.east] infection[young.young.west.mild.mild]     ~ beta[young.young.west.mild.mild]     * state[S.young.west] * state[I.young.west.mild]   / N[young.west] infection[young.young.west.mild.severe]   ~ beta[young.young.west.mild.severe]   * state[S.young.west] * state[I.young.west.severe] / N[young.west] infection[young.young.west.severe.mild]   ~ beta[young.young.west.severe.mild]   * state[S.young.west] * state[I.young.west.mild]   / N[young.west] infection[young.young.west.severe.severe] ~ beta[young.young.west.severe.severe] * state[S.young.west] * state[I.young.west.severe] / N[young.west] infection[young.old.west.mild.mild]       ~ beta[young.old.west.mild.mild]       * state[S.young.west] * state[I.old.west.mild]     / N[old.west] infection[young.old.west.mild.severe]     ~ beta[young.old.west.mild.severe]     * state[S.young.west] * state[I.old.west.severe]   / N[old.west] infection[young.old.west.severe.mild]     ~ beta[young.old.west.severe.mild]     * state[S.young.west] * state[I.old.west.mild]     / N[old.west] infection[young.old.west.severe.severe]   ~ beta[young.old.west.severe.severe]   * state[S.young.west] * state[I.old.west.severe]   / N[old.west] infection[old.young.west.mild.mild]       ~ beta[old.young.west.mild.mild]       * state[S.old.west]   * state[I.young.west.mild]   / N[young.west] infection[old.young.west.mild.severe]     ~ beta[old.young.west.mild.severe]     * state[S.old.west]   * state[I.young.west.severe] / N[young.west] infection[old.young.west.severe.mild]     ~ beta[old.young.west.severe.mild]     * state[S.old.west]   * state[I.young.west.mild]   / N[young.west] infection[old.young.west.severe.severe]   ~ beta[old.young.west.severe.severe]   * state[S.old.west]   * state[I.young.west.severe] / N[young.west] infection[old.old.west.mild.mild]         ~ beta[old.old.west.mild.mild]         * state[S.old.west]   * state[I.old.west.mild]     / N[old.west] infection[old.old.west.mild.severe]       ~ beta[old.old.west.mild.severe]       * state[S.old.west]   * state[I.old.west.severe]   / N[old.west] infection[old.old.west.severe.mild]       ~ beta[old.old.west.severe.mild]       * state[S.old.west]   * state[I.old.west.mild]     / N[old.west] infection[old.old.west.severe.severe]     ~ beta[old.old.west.severe.severe]     * state[S.old.west]   * state[I.old.west.severe]   / N[old.west]"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"constructive-descriptions-of-model-structure","dir":"Articles","previous_headings":"Model Structure and Bookkeeping","what":"Constructive Descriptions of Model Structure","title":"Design Concepts","text":"first step constructive better representation structured vectors. used dot-concatenation represent model strata. example, two-patch SI model epidemiological status geographic location state variable names: S.east, S.west, .east, .west. state vector gets structured becomes convenient describe variables using index table, rows describe state variable. representation can get subsets state vector represent epidemiological status.","code":"state = mp_cartesian(   mp_index(Epi = c(\"S\", \"I\")),   mp_index(Loc = c(\"east\", \"west\")) ) state ##  Epi  Loc ##    S east ##    I east ##    S west ##    I west beta = mp_group(state, \"Epi\") mp_subset(state, Epi = \"S\") ##  Epi  Loc ##    S east ##    S west mp_subset(state, Epi = \"I\") ##  Epi  Loc ##    I east ##    I west"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"structured-vectors","dir":"Articles","previous_headings":"Model Structure and Bookkeeping","what":"Structured Vectors","title":"Design Concepts","text":"column vectors, rows ","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"alternative-engines","dir":"Articles","previous_headings":"","what":"Alternative Engines","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"combining-expression-lists","dir":"Articles","previous_headings":"","what":"Combining Expression Lists","title":"Design Concepts","text":"expression lists really just lists expressions, can combined lists normally combined. example keep dynamics si model separate -reporting reporting delay corrections raw prevalence (TODO: really use incidence).","code":"library(macpan2) si_dynamics = list(     transition_rate = infection ~ beta * S * I / N   , state_update = S ~ S - infection   , state_update = I ~ I + infection ) reporting_correction = list(   post_processing = reports ~ convolution(I, c(0.5, 0.25, 0.25)) ) si = mp_dynamic_model(   expr_list = macpan2:::ExprList(during = c(si_dynamics, reporting_correction)),   unstruc_mats = list(S = 99, I = 1, beta = 0.25, N = 100) ) (si   |> mp_dynamic_simulator(time_steps = 10     , mats_to_return = \"reports\"     , mats_to_save = c(\"I\", \"reports\")   )   |> mp_trajectory() ) ##     matrix time row col    value ## 1  reports    1   0   0 0.873750 ## 2  reports    2   0   0 1.339617 ## 3  reports    3   0   0 1.669899 ## 4  reports    4   0   0 2.080193 ## 5  reports    5   0   0 2.589100 ## 6  reports    6   0   0 3.219119 ## 7  reports    7   0   0 3.997230 ## 8  reports    8   0   0 4.955432 ## 9  reports    9   0   0 6.131141 ## 10 reports   10   0   0 7.567307"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"introduction","dir":"Articles","previous_headings":"","what":"Introduction","title":"Development Principles and Patterns","text":"macpan2 package uses standard S3 object-oriented framework R. objects macpan2 standard R environments, standard S3 class attributes. approach allows us integrate standard generic S3 methods (e.g. print, predict), retaining benefits programming styles common outside R data-code bundling passing reference. can get benefits without dependencies third-party packages R6 instead use standard R tools, unorthodox yet interesting (us) way.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"constructing-and-using-objects","dir":"Articles","previous_headings":"Basics of the macpan2 Object Oriented Framework","what":"Constructing and Using Objects","title":"Development Principles and Patterns","text":"understand macpan2, users developers need understand construct objects. Objects macpan2 S3 class attributes standard R environments additional restrictions. looking restrictions, illustrate basic idea example. macpan2 package comes set vignette(\"example_models\", package = \"macpan2\"). One simple example SIR model stored . path points directory following files. read one files using standard R methods, illustrate objects using CSVReader function. function returns object class CSVReader. get print S3 class object, vector three items. three items? standard S3 method inheritance. doesn’t make sense, doesn’t matter now. also saw item just R environment. later. important thing read function listed. function method, importantly standard S3 method. S3 method? guessed , cover . call methods, like read() method, following way. sir_flows_reader read CSV file configured read. syntax might look strange many R users, used something like . reason sir_reader$read() works without arguments path read stored sir_reader object. can see (almost) everything stored object using ls function. see , along read method, something else called file, just file path reader configured read. Object components like file component, methods, called fields. ’s basic idea use objects macpan2. ’s summary. Objects standard R environments Objects standard R S3 classes Objects fields methods Object methods functions can make use object components","code":"(sir_path = system.file(\"model_library\", \"sir_vax\", package = \"macpan2\")) #> [1] \"/home/runner/work/_temp/Library/macpan2/model_library/sir_vax\" list.files(sir_path) #> [1] \"derivations.json\"            \"flows.csv\"                   #> [3] \"README.md\"                   \"settings.json\"               #> [5] \"trans.csv\"                   \"transmission_dimensions.csv\" #> [7] \"transmission_matrices.csv\"   \"variables.csv\" sir_flows_reader = CSVReader(sir_path, \"flows.csv\") sir_flows_reader #> Classes 'CSVReader', 'Reader', 'Base' <environment: 0x5587b5d73308>  #> read : function ()   #> read_base : function () class(sir_flows_reader) #> [1] \"CSVReader\" \"Reader\"    \"Base\" sir_flows_reader$read() #>      from      to        flow               type from_partition to_partition #> 1       S       I   infection         per_capita            Epi          Epi #> 2       I       R       gamma         per_capita            Epi          Epi #> 3 S.unvax   S.vax vaccination         per_capita        Epi.Vax      Epi.Vax #> 4       S S.unvax       birth  per_capita_inflow            Epi      Epi.Vax #> 5       I S.unvax       birth  per_capita_inflow            Epi      Epi.Vax #> 6       R S.unvax       birth  per_capita_inflow            Epi      Epi.Vax #> 7       S               death per_capita_outflow            Epi         Null #> 8       I               death per_capita_outflow            Epi         Null #> 9       R               death per_capita_outflow            Epi         Null #>   flow_partition from_to_partition from_flow_partition to_flow_partition #> 1            Epi               Vax                 Vax              Null #> 2            Epi               Vax                 Vax              Null #> 3            Vax                                                    Null #> 4            Epi                                                    Null #> 5            Epi                                                    Null #> 6            Epi                                                    Null #> 7            Epi              Null                                  Null #> 8            Epi              Null                                  Null #> 9            Epi              Null                                  Null read.csv(file.path(sir_path, \"flows.csv\")) #>       from       to         flow                type  from_partition #> 1 S        I        infection    per_capita          Epi             #> 2 I        R        gamma        per_capita          Epi             #> 3 S.unvax  S.vax    vaccination  per_capita          Epi.Vax         #> 4 S        S.unvax  birth        per_capita_inflow   Epi             #> 5 I        S.unvax  birth        per_capita_inflow   Epi             #> 6 R        S.unvax  birth        per_capita_inflow   Epi             #> 7 S                 death        per_capita_outflow  Epi             #> 8 I                 death        per_capita_outflow  Epi             #> 9 R                 death        per_capita_outflow  Epi             #>    to_partition  flow_partition  from_to_partition  from_flow_partition #> 1 Epi           Epi             Vax                Vax                  #> 2 Epi           Epi             Vax                Vax                  #> 3 Epi.Vax       Vax                                                     #> 4 Epi.Vax       Epi                                                     #> 5 Epi.Vax       Epi                                                     #> 6 Epi.Vax       Epi                                                     #> 7 Null          Epi             Null                                    #> 8 Null          Epi             Null                                    #> 9 Null          Epi             Null                                    #>   to_flow_partition #> 1              Null #> 2              Null #> 3              Null #> 4              Null #> 5              Null #> 6              Null #> 7              Null #> 8              Null #> 9              Null ls(sir_flows_reader) #> [1] \"file\"      \"read\"      \"read_base\" sir_flows_reader$file #> [1] \"/home/runner/work/_temp/Library/macpan2/model_library/sir_vax/flows.csv\""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"defining-classes","dir":"Articles","previous_headings":"Basics of the macpan2 Object Oriented Framework","what":"Defining Classes","title":"Development Principles and Patterns","text":"define class write function called constructor. aleady seen constructor – CSVReader function . Let’s make . Let’s make class can generate sequences numbers. warm create class nothing contains nothing, illustrates basic boilerplate code creating class. first line constructor uses Base function create environment called self. second line sets selfs S3 class DoesNothing returns newly created S3 object. make class interesting store integer field. looks identical first version, now stored value n. Finally add method can something, change name describe can . Notice fields methods stored self (e.g. self$n) can used methods using $ operator extract value field method self. technical reason works self environment environment every method self environment. fact, self environment thing environment method. seems mind-bending, don’t worry . basics class definitions. ’s summary. Class definitions functions constructing objects class first thing class definition create self environment last thing class definition return self environment S3 object middle class definition one adds methods fields self environment self environment thing environments methods self (don’t worry )","code":"DoesNothing = function() {   self = Base()   return_object(self, \"DoesNothing\") } does_nothing = DoesNothing() does_nothing #> Classes 'DoesNothing', 'Base' <environment: 0x5587b7320c38> DoesNothing = function(n) {   self = Base()   self$n = n  ## save value of the argument in the object   return_object(self, \"DoesNothing\") } does_nothing = DoesNothing(10) does_nothing #> Classes 'DoesNothing', 'Base' <environment: 0x5587b759c8b8> does_nothing$n == 10 #> [1] TRUE SimpleSequence = function(n) {   self = Base()   self$n = n   self$generate = function() seq_len(self$n)   return_object(self, \"SimpleSequence\") } simple_sequence = SimpleSequence(10) simple_sequence$generate() #>  [1]  1  2  3  4  5  6  7  8  9 10"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"objects","dir":"Articles","previous_headings":"Details","what":"Objects","title":"Development Principles and Patterns","text":"macpan2, objects standard R environments S3 class attribute. Therefore, object oriented style involves basic foundational R concepts: environments S3 classes. two types environments setup. first kind environment S3 class attribute environment every function environment ","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"class-definitions","dir":"Articles","previous_headings":"Details","what":"Class Definitions","title":"Development Principles and Patterns","text":"Developers can define class defining standard R function returns instance class. talked bit technical details shouldn’t worry basics defining classes. one technicality worry . Objects created constructor can used methods accessible self environment. example, following code fails. good forces specific method dependencies coming . worse code succeeded following way. ‘work’ now? doesn’t matter never problem just always refer self explicitly methods. particular, proper approach following.","code":"BadClass = function() {   self = Base()   x = 10   self$f = function() x^2   return_object(self, \"BadClass\") } try(BadClass()$f()) #> Error in BadClass()$f() : object 'x' not found x = 10 BadClass()$f() #> [1] 100 GoodClass = function() {   self = Base()   self$x = 10   self$f = function() self$x^2   return_object(self, \"GoodClass\") } GoodClass()$f() #> [1] 100"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"principles","dir":"Articles","previous_headings":"","what":"Principles","title":"Development Principles and Patterns","text":"trade-offs among principles, good guidelines.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"small-classes","dir":"Articles","previous_headings":"Principles","what":"Small Classes","title":"Development Principles and Patterns","text":"able see whole constructor definition single screen – OK doesn’t happen though.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"avoid-modifying-well-tested-classes","dir":"Articles","previous_headings":"Principles","what":"Avoid Modifying Well-Tested Classes","title":"Development Principles and Patterns","text":"Extension better done introducing new classes, rather new methods. Big classes hard reason , test, stabilize.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"linear-inheritance","dir":"Articles","previous_headings":"Principles","what":"Linear Inheritance","title":"Development Principles and Patterns","text":"Classes inherit multiple parents.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"shallow-inheritance-hierarchy","dir":"Articles","previous_headings":"Principles","what":"Shallow Inheritance Hierarchy","title":"Development Principles and Patterns","text":"Parent classes may multiple children, cases hierarchy shallow simple. example, consider alternatives children inherit directly intermediate parent. things like start happen, usually best just extend intermediate parent can inherit directly Base class.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"balance-regeneration-with-consistency","dir":"Articles","previous_headings":"Principles","what":"Balance Regeneration with Consistency","title":"Development Principles and Patterns","text":"naive approach keeping components objects consistent regenerate object every change. continual regeneration can expensive. best avoid trade-much possible making fields cheap compute methods always recompute user asking . fields expensive regenerate therefore need stored regenerated necessary.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"patterns","dir":"Articles","previous_headings":"","what":"Patterns","title":"Development Principles and Patterns","text":"design patterns complying principles.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"alternative-classes","dir":"Articles","previous_headings":"Patterns","what":"Alternative Classes","title":"Development Principles and Patterns","text":"Alternative versions class set methods initial version. needs change becomes easy swap one alternative another. example, Reader() classes single method – $read() – without arguments. Therefore, bit functionality requires data read can modified simply writing new reader swapping old one, without needing modify code calls $read() method. methods alternative classes return type object, obviously return value can vary.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"argument-fields","dir":"Articles","previous_headings":"Patterns","what":"Argument Fields","title":"Development Principles and Patterns","text":"simplest kinds object components, essentially behave lists. Argument fields store arguments constructor. example object two argument fields. fields can accessed using standard $ [[ operators. Note although possible set fields, recommended. Rather one use $refresh() methods described .","code":"A = function(x, y) {   ...   self$x = x   self$y = y   ... } a = A(x = 10, y = 20) a$x == 10 ## TRUE a$y == 20 ## TRUE"},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"static-fields","dir":"Articles","previous_headings":"Patterns","what":"Static Fields","title":"Development Principles and Patterns","text":"Static fields store values derived arguments constructor. Static fields similar argument fields, contain derived quantities depend arguments rather arguments . simple example store sum two arguments static field. Note static fields may need updated $refresh() methods.","code":"A = function(x, y) {   ...   self$z = x + y   ... }"},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"standard-methods","dir":"Articles","previous_headings":"Patterns","what":"Standard Methods","title":"Development Principles and Patterns","text":"Standard methods compute return values derived arguments constructor. methods used cheap run, regeneration consistency balanced. pattern generally preferred option, simplest reason maintain directly ensures consistency.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"composition","dir":"Articles","previous_headings":"Patterns","what":"Composition","title":"Development Principles and Patterns","text":"Objects can composed objects. Composition objects classes looks like . developers users can following. keeps classes small B can methods instead , small classes easier test stabilize. Testing can focus methods directly , can extended composing new classes like B.","code":"A = function(...) {   ...   self$b = B(self)   ... } ... B = function(a) {   ...   self$a = a   ... } a = A(...) a$b$method(...)"},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"refresh-methods","dir":"Articles","previous_headings":"Patterns","what":"Refresh Methods","title":"Development Principles and Patterns","text":"Methods refreshing fields shallow copies fields several composed objects … field gets edited, simplest thing ","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"private-methods","dir":"Articles","previous_headings":"Patterns","what":"Private Methods","title":"Development Principles and Patterns","text":"Private methods used methods class. nothing stoping developer user calling private method, guarantee private method consistent behaviour even exist. communicate privacy, private methods start dot following example shows.","code":"A = function(...) {   ...   self$.private = function(...) {...}   ...   self$public = function(...) {     ...     self.private(...)     ...   } }"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"method-caching","dir":"Articles","previous_headings":"Patterns","what":"Method Caching","title":"Development Principles and Patterns","text":"Developers can manage performance costs computationally expensive methods method caching. developer calls cached method first time, computes result, stores cache, returns result. Subsequent method evaluations simply retrieve cached value, improving efficiency. Developers can ensure consistency invalidating cache whenever objects change, allowing balance cost regeneration need consistency.","code":"A = function(..., method_dependency, ...) {   ...   self$method_dependency = method_dependency   ...   self$expensive_method_1 = function() {     ...   }   ...   self$expensive_method_2 = function() {     ...   }   ...   self$cheap_method = function() {     ...   }   ...   self$modify_dependency = function(...) {     ...     self$cache$expensive_method_1$invalidate()     self$cache$expensive_method_2$invalidate()     ...   }   ...   initialize_cache(self, \"expensive_method_1\", \"expensive_method_2\")   ... }  a = A()  # takes time to return a$expensive_method()   # return immediately by returning the same value computed previously  # and stored in the cache a$expensive_method()  # change object and invalidate the cache to enforce consistency a$modify_dependency(...)  # again takes time to return, but the value is different because the # object was modified a$expensive_method()"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"the-problem","dir":"Articles","previous_headings":"","what":"The Problem","title":"Elementwise Binary Operators","text":"C++ engine every variable matrix. simple situation every variable matrix, elementwise binary operations can defined convenient properties. problem properties standard R, probably case numeric variables matrices. Differences standard R mathematical functions McMasterPandemic C++ engine make difficult test engine. document describes use R elementwise binary operators comparable engine. Consider following three related matrices. relate together x number rows, y number columns. Note although dimensionally related, three objects different shape x y one column row respectively, whereas one row column. relationships might naturally want multiply every column column vector x, R get following error. define rigorously convenient properties expect elementwise binary operators variables matrices, show convert elementwise binary operators R operators properties.","code":"A = matrix(rnorm(6), 3, 2)  # 3 by 2 matrix x = matrix(rnorm(3))        # 3 by 1 matrix y = t(rnorm(2))             # 1 by 2 matrix try(A * x) #> Error in A * x : non-conformable arrays"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"definition-of-an-elementwise-binary-operator-in-the-c-engine","dir":"Articles","previous_headings":"","what":"Definition of an Elementwise Binary Operator in the C++ Engine","title":"Elementwise Binary Operators","text":"Consider generic binary operator, ⊗\\otimes, operates two scalars produce third. can overload operator take two matrices, xx yy, return third matrix, zz. z=x⊗y z = x \\otimes y  elements zz given following expression. $$ z_{,j} = \\cases{ \\begin{array}{lll}   x_{,j} \\otimes y_{,j} & \\text{} n(x) = n(y) & \\text{} m(x) = m(y) & \\text{Standard Hadamard product} \\\\   x_{,j} \\otimes y_{,1} & \\text{} n(x) = n(y) & \\text{} m(y) = 1 & \\text{matrix column times column vector} \\\\   x_{,j} \\otimes y_{1,j} & \\text{} n(y) = 1 & \\text{} m(x) = m(y) & \\text{matrix row times row vector} \\\\   x_{,1} \\otimes y_{,j} & \\text{} n(x) = n(y) & \\text{} m(x) = 1 & \\text{Column vector times matrix column} \\\\   x_{1,j} \\otimes y_{,j} & \\text{} n(x) = 1 & \\text{} m(x) = m(y) & \\text{Row vector times matrix row} \\\\   x_{1,1} \\otimes y_{,j} & \\text{} n(x) = m(x) = 1  & & \\text{Scalar times matrix, vector scalar} \\\\   x_{,j} \\otimes y_{1,1} & \\text{} n(y) = m(y) = 1 & & \\text{Matrix, vector scalar times scalar} \\\\ \\end{array}} $$ functions n()n() m()m() give numbers rows columns respectively.","code":""},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"forcing-a-binary-operator-in-r-to-have-these-properties","dir":"Articles","previous_headings":"","what":"Forcing a Binary Operator in R to have these Properties","title":"Elementwise Binary Operators","text":"consider two matrix-valued operands, x y, standard binary operator, op (e.g. +), R.","code":""},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"step-1","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Step 1","title":"Elementwise Binary Operators","text":"operands shape just operation. works R numeric operations vectorized anyways.","code":"eq = dim(x) == dim(y) if (all(eq)) return(op(x, y))"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"step-2","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Step 2","title":"Elementwise Binary Operators","text":"x either one row one column, define operation arguments swapped otherwise keep operator unchanged.","code":"vec_x = any(dim(x) == 1L) op1 = op if (vec_x) op1 = function(x, y) op(y, x)"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"step-3","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Step 3","title":"Elementwise Binary Operators","text":"Apply base-R sweep function, making sure matrix-like operand comes first.","code":"if (any(eq) & vec_x) return(sweep(y, which(eq), x, op1)) if (any(eq))         return(sweep(x, which(eq), y, op1))"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"implementation-and-examples","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Implementation and Examples","title":"Elementwise Binary Operators","text":"BinaryOperator constructor uses algorithm. examples. tried operations naively, R engine complain. Note algorithm right thing commutative (e.g. *) non-commutative (e.g. ^) operators.","code":"times = BinaryOperator(`*`) pow = BinaryOperator(`^`) (A = matrix(1:6, 3, 2)) #>      [,1] [,2] #> [1,]    1    4 #> [2,]    2    5 #> [3,]    3    6 (x = matrix(1:3, 3)) #>      [,1] #> [1,]    1 #> [2,]    2 #> [3,]    3 (y = matrix(1:2, 1)) #>      [,1] [,2] #> [1,]    1    2 times(A, x) #>      [,1] [,2] #> [1,]    1    4 #> [2,]    4   10 #> [3,]    9   18 pow(A, y) #>      [,1] [,2] #> [1,]    1   16 #> [2,]    2   25 #> [3,]    3   36 try(A * x) #> Error in A * x : non-conformable arrays try(A ^ y) #> Error in A^y : non-conformable arrays identical(times(A, x), times(x, A)) #> [1] TRUE identical(pow(A, x), pow(x, A)) #> [1] FALSE"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"amuse-bouche","dir":"Articles","previous_headings":"","what":"Amuse bouche: a structured SIR model","title":"Engine-Agnostic Model Specification Grammar","text":"key macpan2’s flexible model grammar use functional forms repeat kinds calculations across model structures. instance, consider SIR model two pathogen strains (without co-infections):  , SS, IxI_x, RR numbers individuals susceptible, infected strain xx (AA BB), recovered, respectively, N=S+IA+IB+RN= S + I_A + I_B + R total population size, βx\\beta_x transmission rate strain xx, γ\\gamma recovery rate infected individuals,1 λx=βx(Ix)/N\\lambda_x = \\beta_x (I_x)/N force infection strain xx. can cast model system difference equations, since iterate numerically simulation: St+1=−[βA(IA)t/N+βB(IB)t/N]St,(IA)t+1=−[βA(IA)t/N−γ(IA)t,(IB)t+1=−[βB(IB)t/N−γ(IB)t,Rt+1=−[γ(IA)t+γ(IB)t.\\begin{align} S_{t+1} & = - [\\beta_A (I_A)_t/N + \\beta_B (I_B)_t/N] S_t, \\\\  (I_A)_{t+1} &= \\phantom{-[} \\beta_A (I_A)_t/N - \\gamma (I_A)_t, \\\\  (I_B)_{t+1} &= \\phantom{-[} \\beta_B (I_B)_t/N - \\gamma (I_B)_t, \\\\  R_{t+1} &= \\phantom{-[}  \\gamma (I_A)_t + \\gamma (I_B)_t. \\end{align} force infection, λA=βA(IA)/N\\lambda_A = \\beta_A (I_A)/N λB=βB(IB)/N\\lambda_B = \\beta_B (I_B)/N functional form, , using expression like λ=βI/N\\lambda = \\beta / N. numerically simulating model, doesn’t take much effort write calculation separately something like: However, macpan2, can specify single functional form , instance attach ledger model object tabulates specific instances functional form used define component model. words, ledger enumerate specific subscripted lambda, beta, use time invoke associated functional form simulation. case, two calculations force infection ledger (one calculation per strain), one can easily imagine complicated case. instance, consider relatively simple two-city age-structured metapopulation model 10 age groups within two patches: 10x10x2 = 200 force infection terms form (one per combination age groups capture options susceptible infected interaction, repeated two patches). Using functional forms ledgers allows modeller focus modelling questions, like design model structure choice expressions forces infection, macpan2 handles bookkeeping, matching stratified variables calculating expressions. approach cuts rote repetition setting model calculations, turn reduces opportunity bugs simulation code. also means expanding model can simple updating calculation ledger, rather error-prone editing calculations simulation code. modeller write code cut repetition expanding simple model (many ), macpan2 provides ready-made model specification grammar enables easy model extension, especially building product models, can readily interface fast simulation calibration engines, like TMB.","code":"lambda.A = beta.A * I.A / N lambda.B = beta.B * I.B / N lambda = beta * I / N"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"appetizer-specifying-the-basic-sir-model","dir":"Articles","previous_headings":"","what":"Appetizer: specifying the basic SIR model","title":"Engine-Agnostic Model Specification Grammar","text":"Let’s start specifying basic SIR model, foundation two-strain model , macpan2: St+1=−βStIt/N,+1=−βStIt/N−γIt,Rt+1=−γIt.\\begin{align} S_{t+1} &= -\\beta S_t I_t/N, \\\\  I_{t+1} &= \\phantom{-} \\beta S_t I_t/N - \\gamma I_t, \\\\  R_{t+1} &=  \\phantom{-} \\gamma I_t. \\end{align} helpful set λ=βI/N\\lambda = \\beta /N recast equations : St+1=−λSt,+1=−λSt−γIt,Rt+1=−γIt.\\begin{align} S_{t+1} &= -\\lambda S_t, \\\\  I_{t+1} &=  \\phantom{-} \\lambda S_t - \\gamma I_t, \\\\  R_{t+1} &=  \\phantom{-} \\gamma I_t. \\end{align} Since focus quickstart guide macpan2’s model specification grammar, defined SIR_starter() function sweep details initializing model object rug (now, though revisit later). need know SIR_starter() stage pass inputs define model using model grammar output model object can build simulator. primary focus remainder vignette inputs SIR_starter() created. inputs SIR_starter() two types: index tables containing indices (labels) model quantities, ledgers tabulate specific calculations required simulate model equations (based included functional forms). index tables need specify fall two groups: state: state names, SS, II, RR model equations rate: rate names, β\\beta, γ\\gamma, derived rate λ\\lambda identified two useful functional forms baked SIR_starter(). case, ’re thinking forms necessarily repeated calculations particular model, calculations modeller may want repeat line, expand simple model additional structure (). forms : flow: Unsigned flows one class another form rXrX, r>0r>0 per capita flow rate XX occupancy state flow originates. calculation repeated terms right-hand side recast system difference equations . force infection: prevalence-dependent per capita rate flow susceptible classes infectious classes form λ=βI/N\\lambda = \\beta /N, used calculating infection flows. case, flow form repeated within model equations, force infection form used . ’ve identified force infection functional form since want repeat later expanding two-strain model. Either way, forms already baked SIR_starter(), task creating ledger forms input function. start creating state rate index tables: mp_index() function sets structures like data frames tabulate model quantity labels: Epi column name unimportant simple model, key stratifying model quantities different features (epidemiological status, infection type, age group, location) complicated models. flow form, create two ledgers: infection flow SS II recovery flow II RR pass list flow argument SIR_starter(). specify flows using name state originates (from_states), state goes (to_states), flow rate name (flow_rates). use mp_join() function create infection ledger like : mp_join() function takes options provided argument from_states, to_states, flow_rates, e.g. default creates one entry ledger combination values (.e., full join). However, since one value column, one entry resulting ledger: names arguments mp_join() function tied functional form baked SIR_starter() specified, general modellers can define functional forms corresponding mp_join() argument names however like.2 create recovery ledger similar way: Finally, force_of_infection ledger slightly different corresponds different functional form SIR_starter() (mp_join() argument names different): functional form, need specify transmission_rates infectious_states involved computing force infection, well names want store results calculation (infection_flow_rates) use infection flow calculations. Now can use SIR_starter() function initialize model object: can create model simulator using mp_dynamic_simulator()3, giving model object (model), initial values index (vectors), well number total time steps simulation (time_steps): Note ’ve specified NA lambda calculated us using force infection functional form. can actually simulate model passing model simulator mp_trajectory(): output simulation long data frame: simulation output several columns: matrix: matrix storing values internally, corresponding two index tables, state rate. time: internal time index, time = 1 result first step simulation loop. row: primary label value (row name corresponding matrix). col: secondary label value (column name corresponding matrix). Since outputs model (.e. states rates) specified vectors matrices, column empty entries. TODO: useful? value: numerical value. output can manipulated plotted standard tools, like dplyr ggplot2, e.g.:  (, used base R pipe operator, |>.) prefer make plots base R, can convert long format data wide format: can plot one state like  multiple states plot ","code":"## index tables to label model quantities ------------------------- state <- mp_index(Epi = c(\"S\", \"I\", \"R\")) rate <- mp_index(Epi = c(\"beta\", \"gamma\", \"lambda\")) state ##  Epi ##    S ##    I ##    R rate ##     Epi ##    beta ##   gamma ##  lambda ## infection ledger ------------------------- infection <- mp_join(   from_states = mp_subset(state, Epi = \"S\"),   to_states = mp_subset(state, Epi = \"I\"),    flow_rates = mp_subset(rate, Epi = \"lambda\") ) mp_subset(state, Epi = \"S\") ##  Epi ##    S mp_subset(state, Epi = \"I\") ##  Epi ##    I mp_subset(rate, Epi = \"lambda\") ##     Epi ##  lambda infection ##  from_states to_states flow_rates ##            S         I     lambda ## recovery ledger ------------------------- recovery  <- mp_join(   from_states = mp_subset(state, Epi = \"I\"),   to_states = mp_subset(state, Epi = \"R\"),   flow_rates = mp_subset(rate, Epi = \"gamma\") )  recovery ##  from_states to_states flow_rates ##            I         R      gamma ## force of infection ledger ------------------------- # infection additionally involves the calculation of a force of infection force_of_infection <- mp_join(   infectious_states = mp_subset(state, Epi = \"I\"),   transmission_rates = mp_subset(rate, Epi = \"beta\"),   infection_flow_rates = mp_subset(rate, Epi = \"lambda\") ) ## SIR model object ------------------------- sir <- SIR_starter(   # index tables   state = state,   rate = rate,   # ledgers   flow = list(     infection,     recovery   ),   force_of_infection = force_of_infection ) ## SIR model simulator ------------------------- sir_simulator <- mp_dynamic_simulator(   dynamic_model = sir,   vectors = list(     state = c(S = 999, I = 1, R = 0),     rate = c(beta = 0.25, gamma = 0.1)   ),   time_steps = 100 ) ## SIR model simulation results ------------------------- sir_results <- mp_trajectory(sir_simulator) head(sir_results) ##   matrix time    row col     value ## 1  state    1      S     998.75025 ## 2  state    1      I       1.14975 ## 3  state    1      R       0.10000 ## 4   rate    1   beta       0.25000 ## 5   rate    1  gamma       0.10000 ## 6   rate    1 lambda       0.00025 (sir_results   |> filter(matrix == \"state\") # keep just the state variables at each point in time   |> mutate(state = factor(row, levels = c(\"S\", \"I\", \"R\"))) # to enforce logical state ordering in legend   |> ggplot(aes(time, value, colour = state))   +  geom_line() ) sir_results_wide <- (sir_results     |> dplyr::filter(matrix == \"state\") # keep state variables at each point in time     ## drop unneeded columns before pivoting     |> dplyr::select(-c(matrix, col))     |> tidyr::pivot_wider(id_cols = time, names_from = row) )  head(sir_results_wide, n = 3) ## # A tibble: 3 × 4 ##    time     S     I     R ##   <int> <dbl> <dbl> <dbl> ## 1     1  999.  1.15 0.1   ## 2     2  998.  1.32 0.215 ## 3     3  998.  1.52 0.347 with(sir_results_wide,      plot(x = time,           y = I,           type = \"l\") ) par(las = 1) ## horizontal y-axis ticks matplot(sir_results_wide[, 1],         sir_results_wide[,-1],         type = \"l\",         xlab = \"time\", ylab = \"\") legend(\"left\", col = 1:3, lty = 1:3, legend = state$labels())"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"main-course","dir":"Articles","previous_headings":"","what":"Main course: expanding the basic SIR with additional structure","title":"Engine-Agnostic Model Specification Grammar","text":"previously noted, created force infection functional form (βI/N\\beta / N) despite used define SIR model. However, consider two-strain model , see calculation repeated strain: λA=βAIA/NλB=βBIB/N\\begin{align} \\lambda_A &= \\beta_A I_A/N \\\\  \\lambda_B &= \\beta_B I_B/N \\end{align} Since already form force infection, can easily expand basic SIR strain-related structure get two-strain SIR model. define two-strain model, must specify state rate index tables, well infection, recovery, force_of_infection ledgers. start creating new set indices strains: simple approach define table new state rate indices directly using mp_index() function, : However, approach less flexible want build complex model already simpler, working model (like SIR ) want expand many strata /several different types strata. present alternative approach verbose far flexible. state, want cross II different strains create one II compartment name per strain. can using mp_cartesian() function, takes Cartesian product indices (possible combinations across sets)4: table stores indices associated II compartment.5 combine newly-stratified II indices states remain unchanged using mp_union() function make state index table: update rate index table similarly: infection ledger, let’s see previous code generating yields now (partially) stratifying Strain: , default mp_join() give possible combinations indices (full join), individual indices, denoted values Epi Strain columns, dot-concatenated full quantity labels. model, want two flows: flow S .flow rate lambda.flow S .B flow rate lambda.B words, want Strain index match Strain index lambda. can specify within mp_join() building ledger like : Note syntax argument . list element correspond pairwise join two index tables passed mp_join(). indices involved join correspond dot concatenated list element name (to_states.flow_rates), names coming mp_join()’s argument names (to_states, flow_rates). list element value character string corresponding index table column name upon perform matches. case, value \"Strain\" want “state” labels “flow rate” labels match based Strain index table column (.lambda..B lambda.B). recovery ledger, haven’t stratified gamma R, default full join labels yields exactly flows want: force infection ledger, full join yields many combinations don’t want: want lambda, , beta labels matched Strain column respective index tables. Internally, mp_join() performs pairwise joins, specify three-way argument. Instead, specify two pairwise joins effect: Now ’re ready build two-strain model object simulate :","code":"Strain_indices <- c(\"A\", \"B\") state <- mp_index(   Epi = c(\"S\", rep(\"I\", 2), \"R\"),   Strain = c(\"\", Strain_indices, \"\") )  rate <- mp_index(   Epi = c(rep(c(\"beta\", \"lambda\"), 2), \"gamma\"),   Strain = c(rep(c(\"A\", \"B\"), each = 2), \"\") ) I_indices <- mp_cartesian(   mp_subset(state, Epi = \"I\"),   mp_index(Strain = Strain_indices) )  I_indices ##  Epi Strain ##    I      A ##    I      B state <- mp_union(   mp_subset(state, Epi = \"S\"),   I_indices,    mp_subset(state, Epi = \"R\") )  state ##  Epi Strain ##    S        ##    I      A ##    I      B ##    R rate <-    mp_union(   # stratify rates involved in the infection process by strain   mp_cartesian(     mp_subset(rate, Epi = c(\"beta\", \"lambda\")),     mp_index(Strain = Strain_indices)   ),   # recovery rate will be the same across strains   mp_subset(rate, Epi = \"gamma\") )  rate ##     Epi Strain ##    beta      A ##  lambda      A ##    beta      B ##  lambda      B ##   gamma # infection ledger from before mp_join(   from_states = mp_subset(state, Epi = \"S\"),   to_states = mp_subset(state, Epi = \"I\"),    flow_rates = mp_subset(rate, Epi = \"lambda\") ) ##  from_states to_states flow_rates ##           S.       I.A   lambda.A ##           S.       I.B   lambda.A ##           S.       I.A   lambda.B ##           S.       I.B   lambda.B ## new infection ledger ------------------------- infection <- mp_join(   from_states = mp_subset(state, Epi = \"S\"),   to_states = mp_subset(state, Epi = \"I\"),    flow_rates = mp_subset(rate, Epi = \"lambda\"),   by = list(     to_states.flow_rates = \"Strain\"   ) )  infection ##  from_states to_states flow_rates ##           S.       I.A   lambda.A ##           S.       I.B   lambda.B recovery <- mp_join(     from_states = mp_subset(state, Epi = \"I\"),     to_states = mp_subset(state, Epi = \"R\"),     flow_rates = mp_subset(rate, Epi = \"gamma\") ) recovery ##  from_states to_states flow_rates ##          I.A        R.     gamma. ##          I.B        R.     gamma. mp_join(   infection_flow_rates = mp_subset(rate, Epi = \"lambda\"),   infectious_states = mp_subset(state, Epi = \"I\"),   transmission_rates = mp_subset(rate, Epi = \"beta\") ) ##  infection_flow_rates infectious_states transmission_rates ##              lambda.A               I.A             beta.A ##              lambda.B               I.A             beta.A ##              lambda.A               I.B             beta.A ##              lambda.B               I.B             beta.A ##              lambda.A               I.A             beta.B ##              lambda.B               I.A             beta.B ##              lambda.A               I.B             beta.B ##              lambda.B               I.B             beta.B ## new force of infection ledger ------------------------- force_of_infection <- mp_join(   infection_flow_rates = mp_subset(rate, Epi = \"lambda\"),   infectious_states = mp_subset(state, Epi = \"I\"),   transmission_rates = mp_subset(rate, Epi = \"beta\"),   by = list(     infection_flow_rates.infectious_states = \"Strain\", # first pairwise join     infectious_states.transmission_rates = \"Strain\" # second pairwise join   ) )  force_of_infection ##  infection_flow_rates infectious_states transmission_rates ##              lambda.A               I.A             beta.A ##              lambda.B               I.B             beta.B two_strain_model <- SIR_starter(   # index tables   state = state,   rate = rate,   # ledgers   flow = list(     infection,     recovery   ),   force_of_infection = force_of_infection )  two_strain_simulator <- mp_dynamic_simulator(   dynamic_model = two_strain_model,   vectors = list(     state = c(S = 998, I.A = 1, I.B = 1, R = 0),     rate = c(beta.A = 0.25, gamma = 0.1, beta.B = 0.2)   ),   time_steps = 100 )  two_strain_results <- (mp_trajectory(two_strain_simulator)   |> filter(matrix == \"state\")                     )  levels <- unique(two_strain_results$row) # get state variables in the desired order  (two_strain_results # keep state variables at each point in time   |> mutate(state = factor(row, levels = levels)) # to enforce logical state ordering in plot   |> ggplot(aes(time, value, colour = state))   +  geom_line() )"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"dessert","dir":"Articles","previous_headings":"","what":"Dessert: understanding model simulation in macpan2","title":"Engine-Agnostic Model Specification Grammar","text":"mentioned, ’ve hidden details initializing model object within SIR_starter() function: function definition shows pieces fit together. expressions list expr_list perhaps interesting contains functional forms used simulate model, including explored (unsigned flows, force infection), well didn’t discuss (total inflow, total outflow, state update). ledgers init_vecs just set ensure ledgers initial conditions simulation get attached model object correctly. topics discussed fully future vignette.","code":"## helper function to simplify the exposition in this vigette ----------- SIR_starter <- function(   # index tables for model quantities   state,   rate,   # ledgers tabulating the use of different functional forms   flow, # list of individual ledgers   force_of_infection ){      ## Set up expressions list for each functional form --------------   ## names refer to when the calculation gets performed relative to    ## the simulation time-step loop (before, during, ...)   ## FIXME: we should not be referring to a specific engine in   ## a vignette about an 'engine-agnostic grammar'   expr_list <- mp_tmb_expr_list(     before = list(       ## aggregations         N ~ sum(state)     ),     during = list(       ## force of infections         rate[infection_flow_rates] ~           state[infectious_states] * rate[transmission_rates] / N          ## unsigned individual flows       , flow_per_time ~ state[from_states] * rate[flow_rates]          ## state update       , total_inflow ~ group_sums(flow_per_time, to_states, state)       , total_outflow ~ group_sums(flow_per_time, from_states, state)       , state ~ state + total_inflow - total_outflow     )   )      ## Ledgers for each specific calculation --------------   ledgers <- list(     flow = mp_ledgers(flow),     force_of_infection = mp_ledgers(force_of_infection)   )      ## Initialize vectors from index tables (with all zeros for values) --------------   # used as placeholders for user input   init_vecs <- list(     state = mp_structured_vector(state),     rate = mp_structured_vector(rate)   )      ## Initialize model object -----------------   mp_dynamic_model(     expr_list = expr_list,     ledgers = ledgers,     init_vecs = init_vecs   ) }"},{"path":"https://canmod.github.io/macpan2/articles/example_models.html","id":"finding-example-models","dir":"Articles","previous_headings":"","what":"Finding Example Models","title":"Example Models","text":"macpan2 comes set example model definitions, can listed show_models function. three things can items list: read , use , modify . read , just click links take model. use modify , please continue reading.","code":"show_models()"},{"path":"https://canmod.github.io/macpan2/articles/example_models.html","id":"using-examples","dir":"Articles","previous_headings":"","what":"Using Examples","title":"Example Models","text":"use sir example can read R using following code. see actually generate simulations model see article. use another model, , replace sir another entry dir column .","code":"sir_dir = system.file(\"starter_models\", \"sir\", package = \"macpan2\") sir = mp_tmb_library(sir_dir) print(sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)"},{"path":"https://canmod.github.io/macpan2/articles/example_models.html","id":"modifying-examples","dir":"Articles","previous_headings":"","what":"Modifying Examples","title":"Example Models","text":"take sir jumping-point producing model one may use following code. running code can go files my_sir_dir modify see . Note typically want chose specific directory model instead using tempdir. still need read model usual way. look identical came , ’s just hasn’t modified … yet …","code":"my_sir_dir = file.path(tempdir(), \"my_sir\") mp_model_starter(\"sir\", my_sir_dir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) my_sir = mp_tmb_library(my_sir_dir) print(my_sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)"},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"calibration-defaults","dir":"Articles","previous_headings":"","what":"Calibration Defaults","title":"Specifying Likelihood and Prior Components","text":"calibration interface allows direct specification likelihood prior components. objective function calibration summation negative log likelihoods negative log prior densities. default, interface assumes poisson likelihoods uniform priors. demonstrated objective function calibration example. calibration output shows poisson likelihood used trajectory variable additional objective function terms indicate parameters beta R improper uniform prior density. Indicating prior information parameters.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"customizing-the-objective-function","dir":"Articles","previous_headings":"","what":"Customizing the Objective Function","title":"Specifying Likelihood and Prior Components","text":"specify likelihood /prior variable model can select distribution list available distributions,?macpan2::distribution.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"priors-on-model-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Priors on model parameters","title":"Specifying Likelihood and Prior Components","text":"Specifying priors usually done par argument mp_tmb_calibrator. example prior specification SHIVER model. parameter logit_p, logit transformed proportion p, given normal prior using distribution function macpan2::mp_normal two numeric inputs location standard deviation, sd. remaining parameters given improper uniform prior using macpan2::mp_uniform.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"likelihoods-on-model-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Likelihoods on model parameters","title":"Specifying Likelihood and Prior Components","text":"likelihood can specified trajectory variables calibration set-, identified traj argument mp_tmb_calibrator. SHIVER example, variables hospitalizations(H) reported_incidence specified negative binomial likelihood using macpan2::mp_neg_bin function. likelihoods location parameter set calibration machinery use simulated value trajectory location. dispersion parameter mp_neg_bin required.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"fixed-distributional-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Fixed distributional parameters","title":"Specifying Likelihood and Prior Components","text":"Distributional parameters parameters characterize distribution. Often location standard deviation. default, parameters assumed fixed fit. case previous [Prior Specification] example distributional parameters location sd specified numeric constants. Distributional parameters also assumed fixed set name existing variable model. Ex. mp_normal(sd = \"sd_var\")","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"fitting-distributional-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Fitting Distributional Parameters","title":"Specifying Likelihood and Prior Components","text":"Distributional parameters however, can fit calibration framework addition parameters using macpan2::mp_fit. See ?macpan2::fit_distr_params details. previous example [Likelihood Specification] shows negative binomial dispersion parameter fit mp_fit. numeric value provided dispersion starting value optimization routine. optimization, can see fitted dispersion distributional parameters coefficient table. default, named leading distr_params_ followed distributional parameter name corresponding model variable name.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"distributional-parameter-transformations","dir":"Articles","previous_headings":"Use Cases > Fitting Distributional Parameters","what":"Distributional Parameter Transformations","title":"Specifying Likelihood and Prior Components","text":"Distributional parameters default parameter transformations inherited respective distribution. See default_trans argument distribution (?macpan2::distribution). example, standard deviations definition strictly positive number, log transformation convenient use ensure condition met. Defaults can changed either passing distributional parameter transformation function ?macpan2::transform_distr_param trans_distr_param argument ?macpan2::fit_distr_params functions change single transformation. update transformations, named list transformations ?macpan2::transform_distr_param distributional parameter can given default_trans argument distribution.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"priors-on-distributional-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Priors on distributional parameters","title":"Specifying Likelihood and Prior Components","text":"can specify priors distributional parameters : creating variable model distributional parameter referring distributional parameter name specifying prior focal parameter using distributional parameter name specify prior usual way","code":"spec = (   mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\")      ## 1. update the spec to include a new variable named 'my_var' to serve as   ## the standard deviation parameter for the Normal prior on 'beta'.   ## A numeric value of 0.1 is specified as the default for 'my_var', the    ## starting value in optimization.   |> mp_tmb_insert(default = list(my_var = 0.1)) ) ## generate data for calibration data = mp_simulator(spec, 50, \"infection\") |> mp_trajectory()  ## set-up calibrator cal = mp_tmb_calibrator(     spec   , data   , traj = \"infection\"     ## 2. We set a Normal prior on beta, and set the `sd` argument to 'my_var'     ## (would it ever make sense to use mp_fit for `sd` here?)   , par = list(beta = mp_normal(location = 0.35, sd = mp_nofit(\"my_var\"))       ## 3. setting a log-normal prior on 'my_var'     , my_var = mp_log_normal(1,1)    )   , default = list(beta = 0.25) )  ## we can see the prior density for both 'beta' and 'my_var' in the calibration ## objective function cal$simulator$tmb_model$obj_fn$obj_fn_expr #> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta,  #>     0.35, exp(my_var))) - sum(dnorm(log(my_var), 1, 1)) #> <environment: 0x5650ccd59ba0>  mp_optimize(cal) #> $par #>    params    params  #> 0.2000017 1.0015207  #>  #> $objective #> [1] 53.08736 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 9 #>  #> $evaluations #> function gradient  #>       10       10  #>  #> $message #> [1] \"relative convergence (4)\" mp_tmb_coef(cal) #>       term    mat row col default  type  estimate   std.error #> 1   params   beta   0   0    0.25 fixed 0.2000017 0.009166585 #> 2 params.1 my_var   0   0    0.10 fixed 1.0015207 0.707373865"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"hello-world","dir":"Articles","previous_headings":"","what":"Hello World","title":"Quickstart","text":"vignette shows simulate SI model, think simplest possible model epidemiological transmission. code defining SI model (see short article find example models). Simulating model requires choosing number time-steps run model outputs generate. Syntax simulating macpan2 models designed combine standard data prep plotting tools R, demonstrate following code.  (, used base R pipe operator, |>.) remainder article looks step required create plot detail, discusses alternative approaches.","code":"library(ggplot2) library(dplyr) library(tidyr) library(macpan2) si = mp_tmb_model_spec(     before = S ~ N - I   , during = mp_per_capita_flow(         from     = \"S\"            # compartment from which individuals flow       , to       = \"I\"            # compartment to which individuals flow       , rate     = \"beta * I / N\" # expression giving per-capita flow rate       , abs_rate = \"infection\"    # name of absolute flow rate = beta * I * S/N     )   , default = list(N = 100, I = 1, beta = 0.25) ) print(si) ## --------------------- ## Default values: ## --------------------- ##  matrix row col  value ##       N         100.00 ##       I           1.00 ##    beta           0.25 ##  ## --------------------- ## Before the simulation loop (t = 0): ## --------------------- ## 1: S ~ N - I ##  ## --------------------- ## At every iteration of the simulation loop (t = 1 to T): ## --------------------- ## 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  ##      abs_rate = \"infection\") library(ggplot2) library(dplyr) si_plot = (si    ## macpan2  |> mp_simulator(         time_steps = 50       , outputs = c(\"I\", \"infection\")     )  |> mp_trajectory()    ## dplyr  |> mutate(quantity = case_match(matrix       , \"I\" ~ \"Prevalence\"       , \"infection\" ~ \"Incidence\"     ))    ## ggplot2  |> ggplot()   + geom_line(aes(time, value))   + facet_wrap(~ quantity, scales = \"free\")  + theme_bw() ) print(si_plot)"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"creating-a-simulator","dir":"Articles","previous_headings":"","what":"Creating a Simulator","title":"Quickstart","text":"first step produce simulator object, can used generate simulation results. object can produced using mp_simulator function, takes following arguments. model : model specification object, si. time_steps: many time steps epidemic simulator run ? outputs : model variables return simulation output. default (optional) : Allows one update default parameter values initial conditions provided model specification (see argument default mp_tmb_model_spec function). variables specified default left values specification. si_simulator object contains information required generate model simulations infection 50 time steps, without actually generating simulations. interesting step simulation covered next section. moving explain separate step creating simulator step running simulations. reason two steps optimize performance computationally challenging applications software covered article. step creating simulator object computationally intensive next step actually generating simulations. Therefore separation useful single simulator can used repeatedly generate many different simulations. Three common examples requiring repeated simulations simulator : models stochasticity output different run, calibrating model parameters data using iterative optimization tools, running different scenarios updating certain parameters simulation. macpan2 primarily developed computationally challenging iterative simulation problems, believe better introduce two steps distinct beginning. Although two steps might seem unnecessarily complex within context article, keeping separate make life easier working realistic workflows models.","code":"si_simulator = mp_simulator(     model = si    , time_steps = 50   , outputs = c(\"I\", \"infection\") ) si_simulator ## --------------------- ## Before the simulation loop (t = 0): ## --------------------- ## 1: S ~ N - I ##  ## --------------------- ## At every iteration of the simulation loop (t = 1 to 50): ## --------------------- ## 1: infection ~ S * (beta * I/N) ## 2: S ~ S - infection ## 3: I ~ I + infection"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"generating-simulations","dir":"Articles","previous_headings":"","what":"Generating Simulations","title":"Quickstart","text":"Now simulation engine object, si_simulator, use generate simulation results using mp_trajectory() function. results come long (“narrow”) format, exactly one value per row: simulation results output data frame following columns: matrix: matrix value come ? variables represented matrices, although article consider 1--1 matrices. time: time index 1 time_steps. row, col: Placeholders variable components complicated structured models (covered article, useful example S different age groups geographic locations tracked separately). value: simulated value particular state time step.","code":"si_results = mp_trajectory(si_simulator) si_results |> head(8) ##      matrix time row col     value ## 1         I    1   0   0 1.2475000 ## 2 infection    1   0   0 0.2475000 ## 3         I    2   0   0 1.5554844 ## 4 infection    2   0   0 0.3079844 ## 5         I    3   0   0 1.9383066 ## 6 infection    3   0   0 0.3828223 ## 7         I    4   0   0 2.4134907 ## 8 infection    4   0   0 0.4751841"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"processing-results","dir":"Articles","previous_headings":"","what":"Processing Results","title":"Quickstart","text":"macpan2 provide data manipulation plotting tools (although macpan2helpers). philosophy focus engine modelling interface, provide outputs formats easy use data processing packages, like ggplot2, dplyr, tidyr, readily make use data long format. graphs example, required step renames model variables something makes sense graphical presentation. reproduce , take little care produce tidier dataset. rename state variable disease prevalence (number currently infected individuals). discrete-time model, can reinterpret infection incidence (number newly infected individuals) one time step. Note approach calculating incidence works time period incidence measured corresponds length one time step. assumption met – example time step one day incidence data reported every week – approaches computing incidence covered must taken. can generate ggplot dataset . want use base R plots, can convert long format data wide format using tidyr package.  ","code":"si_results = (si_results   |> mutate(matrix = case_match(matrix       , \"I\" ~ \"Prevalence\"       , \"infection\" ~ \"Incidence\"     ))   |> rename(quantity = matrix)   |> select(time, quantity, value) ) print(head(si_results, 8L)) ##   time   quantity     value ## 1    1 Prevalence 1.2475000 ## 2    1  Incidence 0.2475000 ## 3    2 Prevalence 1.5554844 ## 4    2  Incidence 0.3079844 ## 5    3 Prevalence 1.9383066 ## 6    3  Incidence 0.3828223 ## 7    4 Prevalence 2.4134907 ## 8    4  Incidence 0.4751841 library(tidyr) si_results_wide <- (si_results   |> tidyr::pivot_wider(       , id_cols = time       , names_from = quantity     )   |> rename(Time = time) ) head(si_results_wide, n = 3) ## # A tibble: 3 × 3 ##    Time Prevalence Incidence ##   <int>      <dbl>     <dbl> ## 1     1       1.25     0.248 ## 2     2       1.56     0.308 ## 3     3       1.94     0.383 with(si_results_wide,      plot(x = Time,           y = Incidence) ) par(las = 1) ## horizontal y-axis ticks matplot(     si_results_wide[, 1]   , si_results_wide[,-1]   , type = \"l\"   , xlab = \"Time\", ylab = \"\" ) legend(\"topleft\"   , col = 1:3   , lty = 1:3   , legend = c(\"Prevalence\", \"Incidence\") )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"setup","dir":"Articles","previous_headings":"","what":"Setup","title":"Fitting to Real Data","text":"usual need following packages. don’t , please get usual way (.e. using install.packages). addition, need iidda.api package. set options convenience.","code":"library(macpan2) library(dplyr) library(ggplot2) library(broom.mixed) if (!require(iidda.api)) {   repos = c(       \"https://canmod.r-universe.dev\"     , \"https://cran.r-project.org\"   )   install.packages(\"iidda.api\", repos = repos) } #> Warning in check_rapiclient(): Your installation of rapiclient does not support #> passing vectors to the arguments of iidda.api functions. If you wish to pass #> vectors, please follow installation instructions for rapiclient here: #> https://canmod.r-universe.dev/rapiclient api_hook = iidda.api::ops_staging options(iidda_api_msgs = FALSE, macpan2_verbose = FALSE)"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"one-scarlet-fever-outbreak-in-ontario","dir":"Articles","previous_headings":"","what":"One Scarlet Fever Outbreak in Ontario","title":"Fitting to Real Data","text":"following code pull data single scarlet fever outbreak Ontario ended 1930. data looks like.","code":"scarlet_fever_ontario = api_hook$filter(     resource_type = \"Compilation\"   , dataset_ids = \"canmod-cdi-harmonized\"   , iso_3166_2 = \"CA-ON\"  ## get ontario data   , time_scale = \"wk\"  ## weekly incidence data only    , disease = \"scarlet-fever\"      # get data between 1929-08-01 and 1930-10-01   , period_end_date = \"1929-08-01..1930-10-01\" ) print(scarlet_fever_ontario) #> # A tibble: 61 × 18 #>    basal_disease cases_this_period dataset_id            digitization_id disease #>    <chr>                     <dbl> <chr>                 <chr>           <chr>   #>  1 scarlet-fever                23 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  2 scarlet-fever                27 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  3 scarlet-fever                47 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  4 scarlet-fever                24 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  5 scarlet-fever                24 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  6 scarlet-fever                45 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  7 scarlet-fever                57 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  8 scarlet-fever                46 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #>  9 scarlet-fever                45 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #> 10 scarlet-fever                67 canmod-cdi-harmonized cdi_sf_ca_1924… scarle… #> # ℹ 51 more rows #> # ℹ 13 more variables: historical_disease <chr>, #> #   historical_disease_family <chr>, historical_disease_subclass <chr>, #> #   iso_3166 <chr>, iso_3166_2 <chr>, location <chr>, location_type <chr>, #> #   nesting_disease <chr>, original_dataset_id <chr>, period_end_date <date>, #> #   period_start_date <date>, scan_id <chr>, time_scale <chr> (scarlet_fever_ontario   |> ggplot(aes(period_end_date, cases_this_period))   + geom_line() + geom_point()   + ggtitle(\"Scarlet Fever Incidence in Ontario, Canada\")   + theme_bw() )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"sir-model","dir":"Articles","previous_headings":"","what":"SIR Model","title":"Fitting to Real Data","text":"begin pulling simple sir model model library.","code":"sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") print(sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"modify-model-for-reality","dir":"Articles","previous_headings":"","what":"Modify Model for Reality","title":"Fitting to Real Data","text":"take library model shelf need modify bit realistic. mp_tmb_insert() function, inserts new default values model expressions. first change population size population Ontario time. Second, SIR model assumes cases recorded data, realistic. therefore modify model include -reporting, creating case reports variable given product incidence (.e. weekly infection rate) reporting probability. can print modified model see changes made successfully.","code":"ontario_population = api_hook$filter(     resource_type = \"Compilation\"   , dataset_ids = \"canmod-pop-normalized\"   , iso_3166_2 = \"CA-ON\"  ## get ontario data      # get data between 1929-08-01 and 1930-10-01   , date = \"1929-08-01..1930-10-01\" ) sf_sir = mp_tmb_insert(sir   , default = list(N = median(ontario_population$population)) ) sf_sir = mp_tmb_insert(sf_sir     ## insert this expression ...   , expressions = list(reports ~ infection * report_prob)          ## at the end (i.e. Infinity) of the expressions evaluated     ## 'during' each iteration of the simulation loop ...   , at = Inf     , phase = \"during\"        ## add a new default value for the reporting probability   , default = list(report_prob = 1/300) ) print(sf_sir) #> --------------------- #> Default values: #> --------------------- #>       matrix row col        value #>         beta         2.000000e-01 #>        gamma         1.000000e-01 #>            N         3.393512e+06 #>            I         1.000000e+00 #>            R         0.000000e+00 #>  report_prob         3.333333e-03 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #> 3: reports ~ infection * report_prob"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"preparing-the-data","dir":"Articles","previous_headings":"","what":"Preparing the Data","title":"Fitting to Real Data","text":"first step preparing data macpan2 simulate model considering. simulate \"reports\" variable corresponds reported incidence (number new cases per time-step, case one week, multiplied reporting probability). next step get data format compatible format simulations. particular, need matrix, time, value columns. can omit row col columns, ‘matrices’ model 1--1 scalars.","code":"sir_simulator = mp_simulator(sf_sir   , time_steps = 5   , outputs = \"reports\" ) head(mp_trajectory(sir_simulator)) #>    matrix time row col        value #> 1 reports    1   0   0 0.0006666665 #> 2 reports    2   0   0 0.0007333330 #> 3 reports    3   0   0 0.0008066662 #> 4 reports    4   0   0 0.0008873327 #> 5 reports    5   0   0 0.0009760658 observed_data = (scarlet_fever_ontario   ## select the variables to be modelled -- a time-series of case reports.   |> select(period_end_date, cases_this_period)      ## change the column headings so that they match the columns   ## in the simulated trajectories.   |> mutate(matrix = \"reports\")   |> rename(value = cases_this_period)      ## create a `time` column with the time-step IDs that will correspond   ## to the time-steps in the simulation. this column heading also    ## must match the column with the time-steps in the simulated trajectories   |> mutate(time = seq_along(period_end_date)) ) print(head(observed_data)) #> # A tibble: 6 × 4 #>   period_end_date value matrix   time #>   <date>          <dbl> <chr>   <int> #> 1 1929-08-03         23 reports     1 #> 2 1929-08-10         27 reports     2 #> 3 1929-08-17         47 reports     3 #> 4 1929-08-24         24 reports     4 #> 5 1929-08-31         24 reports     5 #> 6 1929-09-07         45 reports     6"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"set-up-the-optimizer","dir":"Articles","previous_headings":"","what":"Set up the Optimizer","title":"Fitting to Real Data","text":"Now can create object can calibrated. assert fit beta, gamma, (initial value ) , report_prob. Note can choose fit parameters default list model spec. particular, default list model requires initial number infectious individuals, whereas S derived simulation loop S ~ N - - R.","code":"sir_cal = mp_tmb_calibrator(     spec = sf_sir   , data = observed_data      ## name the trajectory variable, with a name that   ## is the same in both the spec and the data   , traj = \"reports\"        ## fit the following parameters   , par = c(\"beta\", \"gamma\", \"I\", \"report_prob\") ) print(sf_sir) #> --------------------- #> Default values: #> --------------------- #>       matrix row col        value #>         beta         2.000000e-01 #>        gamma         1.000000e-01 #>            N         3.393512e+06 #>            I         1.000000e+00 #>            R         0.000000e+00 #>  report_prob         3.333333e-03 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #> 3: reports ~ infection * report_prob"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"run-the-optimization","dir":"Articles","previous_headings":"","what":"Run the Optimization","title":"Fitting to Real Data","text":"good start. warnings necessarily bad, might get us thinking.","code":"sir_opt = mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"examine-the-fit","dir":"Articles","previous_headings":"","what":"Examine the fit","title":"Fitting to Real Data","text":"OK, things great. convergence code 1, indicating model converge (convergence == 0 good). Examining parameter estimates, stored internally calibrator object, things get worse. doesn’t look right! high beta gamma values, confidence intervals enormous overlap zero. model fit doesn’t look bad.  going ? Can modify model /fitting procedure get reasonable parameter estimates reasonable trajectory?","code":"print(sir_opt) #> $par #>     params     params     params     params  #> 34.7694070 34.6536331  2.0572289  0.3480618  #>  #> $objective #> [1] 428.1971 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 143 #>  #> $evaluations #> function gradient  #>      200      144  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" mp_tmb_coef(sir_cal, conf.int = TRUE) #>       term         mat row col     default  type   estimate  std.error #> 1   params        beta   0   0 0.200000000 fixed 34.7694070 25.7158953 #> 2 params.1       gamma   0   0 0.100000000 fixed 34.6536331 25.7160472 #> 3 params.2           I   0   0 1.000000000 fixed  2.0572289  3.0405887 #> 4 params.3 report_prob   0   0 0.003333333 fixed  0.3480618  0.2575428 #>      conf.low  conf.high #> 1 -15.6328217 85.1716356 #> 2 -15.7488932 85.0561594 #> 3  -3.9022155  8.0166732 #> 4  -0.1567128  0.8528364 fitted_data = mp_trajectory_sd(sir_cal, conf.int = TRUE) (observed_data   |> ggplot()   + geom_point(aes(time, value))   + geom_line(aes(time, value)     , data = fitted_data   )   + geom_ribbon(aes(time, ymin = conf.low, ymax = conf.high)     , data = fitted_data     , alpha = 0.2     , colour = \"red\"   )   + theme_bw()   + facet_wrap(~matrix, ncol = 1, scales = \"free\") )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"fixing-the-optimization-problem","dir":"Articles","previous_headings":"","what":"Fixing the Optimization Problem","title":"Fitting to Real Data","text":"One way address lack convergence optimizer assess degree parameter estimates biologically reasonable. Take recovery rate, estimated gamma ~ 26.5 per time-step. Given time-step one week model, estimate implies individuals recover scarlet fever 1/26.5 weeks – much less day. quick search suggests recovery rate reasonable scarlet fever, rough guess infectious stage lasts one week much plausible 1/26.5 weeks. Now look transmission rate, beta. also estimated pretty large, interesting large standard errors beta gamma. standard errors suggest estimates precise. However, estimated correlation beta gamma close 1, suggesting many values parameters fit data well long similar magnitude. diagnosis, correct, suggests data sufficiently informative identify values beta gamma. Resolving identifiability issues often best done introducing prior information, rough guess gamma close 1. simplest way include prior information move gamma pars argument mp_tmb_calibrator default argument, . calibration specification try jointly fit beta gamma, rather fits beta assuming gamma = 1. warnings, now optimizer converges. standard errors coefficient table fixed effect correlations seem plausible. fit looks similar four-parameter model, consistent diagnosis non-identifiability.  Caution: Ben, paper always recommend careful prior information included without prior uncertainty? one (Elderd, Dukic, Dwyer 2006)","code":"mp_tmb_fixef_cov(sir_cal) |> cov2cor() #>                   beta      gamma          I report_prob #> beta         1.0000000  1.0000000 -0.9998561   0.9996857 #> gamma        1.0000000  1.0000000 -0.9998553   0.9996870 #> I           -0.9998561 -0.9998553  1.0000000  -0.9993009 #> report_prob  0.9996857  0.9996870 -0.9993009   1.0000000 sir_cal_assume_gamma = mp_tmb_calibrator(     spec = sf_sir   , data = observed_data      ## name the trajectory variable, with a name that   ## is the same in both the spec and the data   , traj = \"reports\"        ## fit the following parameters   , par = c(\"beta\", \"I\", \"report_prob\")   , default = list(gamma = 1) ) sir_opt_assume_gamma = mp_optimize(sir_cal_assume_gamma) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation print(sir_opt_assume_gamma) #> $par #>       params       params       params  #> 1.121602e+00 1.878305e+03 1.125689e-02  #>  #> $objective #> [1] 430.0021 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 79 #>  #> $evaluations #> function gradient  #>      131       80  #>  #> $message #> [1] \"relative convergence (4)\" mp_tmb_coef(sir_cal_assume_gamma) #>       term         mat row col     default  type     estimate    std.error #> 1   params        beta   0   0 0.200000000 fixed 1.121602e+00 1.801964e-03 #> 2 params.1           I   0   0 1.000000000 fixed 1.878305e+03 5.445606e+01 #> 3 params.2 report_prob   0   0 0.003333333 fixed 1.125689e-02 1.927763e-04 mp_tmb_fixef_cov(sir_cal_assume_gamma) |> cov2cor() #>                   beta          I report_prob #> beta         1.0000000 -0.7988821  -0.7608921 #> I           -0.7988821  1.0000000   0.5802420 #> report_prob -0.7608921  0.5802420   1.0000000 fitted_data = mp_trajectory_sd(sir_cal_assume_gamma, conf.int = TRUE) (observed_data   |> ggplot()   + geom_point(aes(time, value))   + geom_line(aes(time, value)     , data = fitted_data   )   + geom_ribbon(aes(time, ymin = conf.low, ymax = conf.high)     , data = fitted_data     , alpha = 0.2     , colour = \"red\"   )   + theme_bw()   + facet_wrap(~matrix, ncol = 1, scales = \"free\") )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"learning-the-functional-form-of-time-variation-in-transmission-new","dir":"Articles","previous_headings":"","what":"Learning the Functional form of Time Variation in Transmission (New!)","title":"Fitting to Real Data","text":"Let’s get bit data see two seasons.  Prepare fit data. make function can easily update dimension radial basis. also convenient make function plotting results Now try fitting number different dimensions.        Interestingly now managed fit gamma much slower recovery rate. Expected time R box one year! believeable, point make easier fit models can try things.","code":"scarlet_fever_ontario = api_hook$filter(     resource_type = \"Compilation\"   , dataset_ids = \"canmod-cdi-harmonized\"   , iso_3166_2 = \"CA-ON\"  ## get ontario data   , time_scale = \"wk\"  ## weekly incidence data only    , disease = \"scarlet-fever\"      # get data between 1929-08-01 and 1931-10-01   , period_end_date = \"1929-08-01..1931-10-01\"   ) (scarlet_fever_ontario   |> ggplot(aes(period_end_date, cases_this_period))   + geom_line() + geom_point()   + ggtitle(\"Scarlet Fever Incidence in Ontario, Canada\")   + theme_bw() ) observed_data = (scarlet_fever_ontario   ## select the variables to be modelled -- a time-series of case reports.   |> select(period_end_date, cases_this_period)      ## change the column headings so that they match the columns   ## in the simulated trajectories.   |> mutate(matrix = \"reports\")   |> rename(value = cases_this_period)      ## create a `time` column with the time-step IDs that will correspond   ## to the time-steps in the simulation. this column heading also    ## must match the column with the time-steps in the simulated trajectories   |> mutate(time = seq_along(period_end_date)) ) print(head(observed_data)) #> # A tibble: 6 × 4 #>   period_end_date value matrix   time #>   <date>          <dbl> <chr>   <int> #> 1 1929-08-03         23 reports     1 #> 2 1929-08-10         27 reports     2 #> 3 1929-08-17         47 reports     3 #> 4 1929-08-24         24 reports     4 #> 5 1929-08-31         24 reports     5 #> 6 1929-09-07         45 reports     6 make_rbf_calibrator = function(dimension) {   mp_tmb_calibrator(       spec = sf_sir     , data = observed_data     , traj = \"reports\"            ## -----------------------------     ## this is the key bit     , tv = mp_rbf(\"beta\", dimension)     ## -----------------------------          , par = c(\"gamma\", \"I\", \"report_prob\")   ) } plot_fit = function(cal_object) {   fitted_data = mp_trajectory_sd(cal_object, conf.int = TRUE)   (observed_data     |> ggplot()     + geom_point(aes(time, value))     + geom_line(aes(time, value)       , data = fitted_data       , colour = \"red\"     )     + geom_ribbon(aes(time, ymin = conf.low, ymax = conf.high)       , data = fitted_data       , alpha = 0.2       , colour = \"red\"     )     + theme_bw()   ) } sir_cal = make_rbf_calibrator(dimension = 1) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>       params       params       params       params       params  #>   1.07372447 365.34139607   0.21804031   0.09069968   0.86580386  #>  #> $objective #> [1] 2897.368 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 150 #>  #> $evaluations #> function gradient  #>      174      151  #>  #> $message #> [1] \"iteration limit reached without convergence (10)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 2) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>     params     params     params     params     params     params  #>  0.4662692 15.7705637  8.5178748 -0.5631177 -0.6997072  0.6673706  #>  #> $objective #> [1] 2977.803 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 150 #>  #> $evaluations #> function gradient  #>      200      150  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 3) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>        params        params        params        params        params  #>  7.480423e-01  7.126562e+03  5.678344e-03 -1.637587e-01 -2.970186e-02  #>        params        params  #>  9.244461e-01  6.246204e-01  #>  #> $objective #> [1] 1574.227 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 67 #>  #> $evaluations #> function gradient  #>       98       68  #>  #> $message #> [1] \"relative convergence (4)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 4) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>      params      params      params      params      params      params  #>  1.24671910 61.38245959  0.16124566  0.40605614 -0.11477326  0.33939236  #>      params      params  #> -0.07429845  0.61040344  #>  #> $objective #> [1] 1601.549 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 129 #>  #> $evaluations #> function gradient  #>      200      130  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 5) mp_optimize(sir_cal) #> $par #>       params       params       params       params       params       params  #> -0.003169677 50.290111756 30.026102089 -4.450364816  1.919450463 -6.177605279  #>       params       params       params  #>  1.776699439 -7.022692636  0.596297469  #>  #> $objective #> [1] 1433.989 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 122 #>  #> $evaluations #> function gradient  #>      200      122  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 6) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>     params     params     params     params     params     params     params  #>  0.7802570  7.7900568  5.2024837 -0.2791101  0.2589907 -0.5956717  0.3101396  #>     params     params     params  #> -0.3747950 -0.1376810  0.5863554  #>  #> $objective #> [1] 1441.466 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 128 #>  #> $evaluations #> function gradient  #>      200      128  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 7) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>      params      params      params      params      params      params  #>  0.02862238 13.83679544  6.50568272 -0.64364604 -1.38502686 -0.17206797  #>      params      params      params      params      params  #> -3.83455289 -0.06296071 -1.56407525 -3.70588098  0.58017538  #>  #> $objective #> [1] 1471.266 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 116 #>  #> $evaluations #> function gradient  #>      200      116  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) mp_tmb_coef(sir_cal) #>         term           mat row col     default  type    estimate   std.error #> 1     params         gamma   0   0 0.100000000 fixed  0.02862238  0.00652316 #> 2   params.1             I   0   0 1.000000000 fixed 13.83679544 19.17824368 #> 3  params.10 prior_sd_beta   0   0 1.000000000 fixed  0.58017538  0.01825558 #> 4   params.2   report_prob   0   0 0.003333333 fixed  6.50568272  9.02118967 #> 5   params.3 time_var_beta   0   0 0.000000000 fixed -0.64364604  0.18346250 #> 6   params.4 time_var_beta   1   0 0.000000000 fixed -1.38502686  0.14960302 #> 7   params.5 time_var_beta   2   0 0.000000000 fixed -0.17206797  0.11830797 #> 8   params.6 time_var_beta   3   0 0.000000000 fixed -3.83455289  0.13803399 #> 9   params.7 time_var_beta   4   0 0.000000000 fixed -0.06296071  0.16608048 #> 10  params.8 time_var_beta   5   0 0.000000000 fixed -1.56407525  0.10524492 #> 11  params.9 time_var_beta   6   0 0.000000000 fixed -3.70588098  0.24480729 mp_tmb_calibrator(     spec = sf_sir   , data = observed_data   , traj = \"reports\"     , tv = mp_rbf(\"beta\", dimension = 7)   , par = c(\"gamma\", \"I\", \"report_prob\")   , outputs = c(\"reports\", \"beta\") ) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #> 2: outputs_var_beta ~ group_sums(values_var_beta * time_var_beta[col_indexes_beta], row_indexes_beta, outputs_var_beta) #> 3: outputs_var_beta ~ c(outputs_var_beta[0], outputs_var_beta) #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: beta ~ exp(time_var(outputs_var_beta, data_time_indexes_beta)) #> 2: infection ~ S * (I * beta/N) #> 3: recovery ~ I * (gamma) #> 4: S ~ S - infection #> 5: I ~ I + infection - recovery #> 6: R ~ R + recovery #> 7: reports ~ infection * report_prob #>  #> --------------------- #> After the simulation loop (t = T + 1): #> --------------------- #> 1: sim_reports ~ rbind_time(reports, obs_times_reports) #>  #> --------------------- #> Objective function: #> --------------------- #> ~-sum(dpois(obs_reports, clamp(sim_reports))) - sum(dnorm(values_var_beta, 0, prior_sd_beta))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"decomposition-of-state-dependent-rates","dir":"Articles","previous_headings":"","what":"Decomposition of State-Dependent Rates","title":"State-Dependent Rates","text":"vast majority compartmental models contain flows depend states compartments directly involved flows. example, magnitude flow compartment compartment B depend another compartment, C. important example dependencies infection, use terminology infection processes. However, model subsume large number flows special cases. Let ss xx subsets state vector. length-nn vector ss contains -compartments – typically compartments susceptible infection – set flows. length-mm vector xx contains compartments – typically infectious compartments – affect flows. components xx need affect components yy need affect . Note keep track -compartments flows matter (think). define nn--mm transmission matrix following decomposition. T=diag(p)Bdiag(c) \\DeclareMathOperator{\\diag}{diag} T = \\diag(p) B \\diag(c) decomposition involves following terms. pp – length-nn vector susceptibilities ss state BB – nn--mm matrix contacts xx ss state cc – length-mm vector infectivities xx state alternative way write transmission matrix decomposition – prefer accurate representation actual computations – using element-wise operations. ∘\\circ element-wise product following. T=p∘B∘c⊤ T = p \\circ B \\circ c^\\top expression column vector pp element-wise multiplied column BB, row product element-wise multiplied row vector c⊤c^\\top, ⊤\\top matrix transpose operator. vector containing per-capita flow rates ss states following. λ=Tx \\lambda = Tx λ\\lambda vector often called force infection. finally absolute flow rates ss states following. r=λ∘s \\DeclareMathOperator{\\diag}{diag} r = \\lambda \\circ s","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir","dir":"Articles","previous_headings":"","what":"Example – SIR","title":"State-Dependent Rates","text":"ss vector contains single state, S, xx contains . case nn mm 1, components 1--1 follows. p=1p = 1 – susceptibility B=1B = 1 – contact matrix c=σNc = \\frac{\\sigma}{N} – infectivity Therefore following transmission matrix, per-capita flow rate vector, absolute flow rate vector. T=σNT = \\frac{\\sigma}{N} λ=σNI\\lambda = \\frac{\\sigma}{N} r=σNISr = \\frac{\\sigma}{N} overly simple hopefully clarifying example decided put σ\\sigma 1N\\frac{1}{N} components, pp, BB, cc. point somewhat mechanistic somewhat general decomposition transmission, start working complex models combining model modules (e.g. combining SEIR age spatial structure) way conveniently combine modules resulting transmission rates make mechanistic sense.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"product-models","dir":"Articles","previous_headings":"","what":"Product Models","title":"State-Dependent Rates","text":"Now consider two models, following triples representing transmission decomposition. (p1,B1,c1) (p_1, B_1, c_1) (p2,B2,c2) (p_2, B_2, c_2) Note subscripts represent model, components vectors matrices. dimensions two models n1,m1n_1, m_1 n2,m2n_2, m_2. Taking product two models results following triple. (p,B,c)=(p1⊗p2,B1⊗B2,c1⊗c2) (p, B, c) = (p_1\\otimes p_2, B_1\\otimes B_2, c_1\\otimes c_2) ⊗\\otimes Kronecker product. leads n1n2n_1n_2--1 column vector, pp, n1n2n_1n_2--m1m2m_1m_2 matrix, BB, m1m2m_1m_2--1 column vector cc. also x1,x2x_1, x_2 s1,s2s_1, s_2 combine xx ss. need make distinction factor models transmission without. example, SIR model clearly transmission, factor model just age groups . pure age model distinguish infectious susceptible people, process considers aging. Nevertheless age model becomes combined model transmission, want ready combined. make age model – factor model without transmission – ready combined model includes transmission need two things. First need account fact states may appear xx ss (e.g. young people can infectious susceptible). Second need include parameters used factor model’s processes used combined model includes transmission (e.g. age model needs contact matrix even though contact processes affect aging, process age model). next example illustrates ideas.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir-times-age","dir":"Articles","previous_headings":"","what":"Example – SIR times age","title":"State-Dependent Rates","text":"take product SIR model two-age-group factor model. components transmission decomposition particular age-group factor model follows. susceptibility: p=[11]p = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix} contact matrix: B=[q(1−q)(1−q)q]B = \\begin{bmatrix} q & (1 - q) \\\\ (1 - q) & q \\end{bmatrix} infectivity: c=[σyoungσyoung]c = \\begin{bmatrix} \\sigma_\\text{young} \\\\ \\sigma_\\text{young} \\end{bmatrix} qq probability given contact individuals age. symmetric contact matrix, didn’t need . also decided susceptibility depend age, absolutely parameterizing vector. little odd refer decomposition transmission, age-model contains aging processes include transmission. However, including transmission decomposition necessary prepare model combination model transmission. Taking product age model SIR model following transmission decomposition. susceptibility: p=[11]p = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix} contact matrix: B=[q(1−q)(1−q)q]B = \\begin{bmatrix} q & (1 - q) \\\\ (1 - q) & q \\end{bmatrix} infectivity: c=σN[σyoungσold]c = \\frac{\\sigma}{N}\\begin{bmatrix} \\sigma_\\text{young} \\\\ \\sigma_\\text{old} \\end{bmatrix} product model xx contains .young .old ss contains S.young S.old. transmission matrix can obtained multiplying three components decomposition follows. T=[11]∘[q(1−q)(1−q)q]∘σN[σyoungσold]=σN[qσyoung(1−q)σold(1−q)σyoungqσold] T = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix}  \\circ \\begin{bmatrix} q & (1 - q) \\\\ (1 - q) & q \\end{bmatrix}  \\circ \\frac{\\sigma}{N}\\begin{bmatrix} \\sigma_\\text{young} & \\sigma_\\text{old} \\end{bmatrix} = \\frac{\\sigma}{N} \\begin{bmatrix} q \\sigma_\\text{young} & (1 - q) \\sigma_\\text{old} \\\\ (1 - q) \\sigma_\\text{young} & q \\sigma_\\text{old} \\end{bmatrix} force infection vector product TT x=[IyoungIold]x = \\begin{bmatrix}I_{\\text{young}} \\\\ I_{\\text{old}}\\end{bmatrix} λ=σN[qσyoungIyoung+(1−q)σoldIold(1−q)σyoungIyoung+qσoldIold] \\lambda = \\frac{\\sigma}{N} \\begin{bmatrix} q \\sigma_\\text{young} I_{\\text{young}} + (1-q) \\sigma_\\text{old} I_{\\text{old}} \\\\ (1-q) \\sigma_\\text{young} I_{\\text{young}} + q \\sigma_\\text{old} I_{\\text{old}} \\end{bmatrix}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir-with-multiple-i-boxes-times-age","dir":"Articles","previous_headings":"","what":"Example – SIR with multiple I-boxes times age","title":"State-Dependent Rates","text":"example SIR model n=1n = 1 susceptible class m=2m = 2 infectious classes – mild severe – following transmission decomposition. susceptibility: p=1p = 1 contact matrix: B=[11]B = \\begin{bmatrix} 1 & 1 \\end{bmatrix} infectivity: c=1N[σmildσsevere]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\\\ \\sigma_\\text{severe} \\end{bmatrix} Multiplying decomposition age model (order) gives following model n=2n = 2 susceptible compartments m=4m = 4 infectious compartments. susceptibility: p=[11]p = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix} contact matrix: B=[q(1−q)q(1−q)(1−q)q(1−q)q]B = \\begin{bmatrix} q & (1 - q) & q & (1 - q) \\\\ (1 - q) & q & (1 - q) & q \\end{bmatrix} infectivity: c=1N[σmildσyoungσmildσoldσsevereσyoungσsevereσold]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\sigma_\\text{young} \\\\ \\sigma_\\text{mild} \\sigma_\\text{old}\\\\ \\sigma_\\text{severe} \\sigma_\\text{young}\\\\ \\sigma_\\text{severe}\\sigma_\\text{old} \\end{bmatrix} non-square contact matrix might seem weird, fine modelling contacts two susceptible classes four infectious classes. One write 22--44 transmission matrix, don’t think informative. informative write component force infection vector, say young people. λyoung=1N(qσmildσyoungImild,young+(1−q)σmildσoldImild,old+qσsevereσyoungIsevere,young+(1−q)σsevereσoldIsevere,old) \\begin{array}{rrrrrrr} \\lambda_{\\text{young}} = \\frac{1}{N}  & ( & & q      \\sigma_\\text{mild}    \\sigma_\\text{young}  I_{\\text{mild},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{mild}    \\sigma_\\text{old}    I_{\\text{mild},\\text{old}} \\\\ & & + & q      \\sigma_\\text{severe}  \\sigma_\\text{young}  I_{\\text{severe},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{severe}  \\sigma_\\text{old}    I_{\\text{severe},\\text{old}} & ) \\\\ \\end{array} first term, example, gives contribution force infection due contacts young susceptible individuals mildly infected young individuals.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir-with-multiple-i-boxes-and-partial-immunity-times-age","dir":"Articles","previous_headings":"","what":"Example – SIR with multiple I-boxes and partial immunity times age","title":"State-Dependent Rates","text":"starting approach ‘real’ models now. SIR model R box can now flow back , immunity gained infection recovery imperfect. model feature means ss vector two states, S R, n=2n = 2. xx vector contains I_mild I_severe, m=2m = 2 well. transmission decomposition looks like . susceptibility: p=[11−π]p = \\begin{bmatrix} 1 \\\\ 1 - \\pi \\end{bmatrix} contact matrix: B=[1111]B = \\begin{bmatrix} 1 & 1 \\\\ 1 & 1 \\end{bmatrix} infectivity: c=1N[σmildσsevere]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\\\ \\sigma_\\text{severe} \\end{bmatrix} π\\pi efficacy immunity reinfection. product model age looks like . susceptibility: p=[111−π1−π]p = \\begin{bmatrix} 1 \\\\ 1 \\\\ 1- \\pi \\\\ 1-\\pi \\end{bmatrix} contact matrix: B=[q(1−q)q(1−q)(1−q)q(1−q)qq(1−q)q(1−q)(1−q)q(1−q)q]B = \\begin{bmatrix} q & (1 - q) & q & (1 - q) \\\\ (1 - q) & q & (1 - q) & q  \\\\ q & (1 - q) & q & (1 - q) \\\\ (1 - q) & q & (1 - q) & q \\end{bmatrix} infectivity: c=1N[σmildσyoungσmildσoldσsevereσyoungσsevereσold]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\sigma_\\text{young} \\\\ \\sigma_\\text{mild} \\sigma_\\text{old}\\\\ \\sigma_\\text{severe} \\sigma_\\text{young}\\\\ \\sigma_\\text{severe}\\sigma_\\text{old} \\end{bmatrix} force infection young individuals R box, example, given following expression λR,young=1−πN(qσmildσyoungImild,young+(1−q)σmildσoldImild,old+qσsevereσyoungIsevere,young+(1−q)σsevereσoldIsevere,old) \\begin{array}{rrrrrr} \\lambda_{\\text{R,young}} = \\frac{1-\\pi}{N} & ( & & q      \\sigma_\\text{mild}    \\sigma_\\text{young}  I_{\\text{mild},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{mild}    \\sigma_\\text{old}    I_{\\text{mild},\\text{old}} \\\\ & & + & q      \\sigma_\\text{severe}  \\sigma_\\text{young}  I_{\\text{severe},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{severe}  \\sigma_\\text{old}    I_{\\text{severe},\\text{old}} & ) \\\\ \\end{array} Note almost identical expression λyoung\\lambda_\\text{young} , factor, 1−π1-\\pi, giving reduction transmission conferred immunity. λR,young=(1−π)λyoung \\lambda_{\\text{R,young}} = (1-\\pi) \\lambda_{\\text{young}}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example","dir":"Articles","previous_headings":"","what":"Example","title":"State-Dependent Rates","text":"Assume SI model times young-old model. Variables.csv","code":"Epi,        Age S,          young I,          young S,          old I,          old susceptibility,   contact"},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"bookkeeping-in-progress","dir":"Articles","previous_headings":"","what":"Bookkeeping (in progress)","title":"State-Dependent Rates","text":"Index element ss ii element xx jj. can define per-capita rate individuals flow sis_i compartment following decomposition. ri=piλi r_i = p_i \\lambda_i components decomposition follows. pip_i: susceptibility (e.g. complement vaccine efficacy) λi\\lambda_i: force infection definition, absolute rate flow sis_i given risir_i s_i. force infection . λi=∑jBijcjxj \\lambda_i = \\sum_j B_{ij}c_jx_j","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"branching-flows-and-process-error","dir":"Articles","previous_headings":"","what":"Branching Flows and Process Error","title":"ODE Solvers, Process Error, and Difference Equations","text":"","code":"siv = mp_tmb_model_spec(     before = list(S ~ N - I - V)   , during = list(         mp_per_capita_flow(\"S\", \"I\", infection ~ beta * I / N)       , mp_per_capita_flow(\"S\", \"V\", vaccination ~ rho)     )   , default = list(I = 1, V = 0, N = 100, beta = 0.25, rho = 0.1) ) print(siv) #> --------------------- #> Default values: #> --------------------- #>  matrix row col  value #>       I           1.00 #>       V           0.00 #>       N         100.00 #>    beta           0.25 #>     rho           0.10 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - V #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ beta *  #>      I/N) #> 2: mp_per_capita_flow(from = \"S\", to = \"V\", rate = vaccination ~  #>      rho) (siv   |> mp_euler_multinomial()  |> mp_simulator(50, \"infection\")  |> mp_trajectory()  |> ggplot()   + geom_line(aes(time, value)) )"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"internal-design","dir":"Articles","previous_headings":"","what":"Internal Design","title":"ODE Solvers, Process Error, and Difference Equations","text":"","code":"sir = mp_tmb_model_spec(   during = list(       N ~ S + I + R     , mp_per_capita_flow(\"S\", \"I\", \"beta * I / N\", \"infection\")     , mp_per_capita_flow(\"I\", \"R\", \"(1 - p) * gamma\", \"recovery\")     , mp_per_capita_flow(\"I\", \"D\", \"p * gamma\", \"death\")   ) )"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"changecomponent-classes","dir":"Articles","previous_headings":"Internal Design","what":"ChangeComponent() classes","title":"ODE Solvers, Process Error, and Difference Equations","text":"Model specs contain set three lists: * : instructions run simulation loop begins. * : instructions run iteration simulation loop. * : instructions run simulation loop ends. simplest way define lists using two-sided R formulas. list one may specify different types list components, class ChangeComponent. Internally, standard R formulas converted object class Formula, simplest kind ChangeComponent. Another important ChangeComponent PerCapitaFlow type, used standard flows one compartment another. list change components, just field ensuring elements valid ChangeComponent objects, can obtained using change_components() method model spec object. ChangeComponent objects must following methods.","code":"cc = sir$change_components() print(cc) #> [[1]] #> N ~ S + I + R #>  #> [[2]] #> From: S #> To: I #> Per-capita rate expression: beta * I/N #> Absolute rate symbol: infection #> [[3]] #> From: I #> To: R #> Per-capita rate expression: (1 - p) * gamma #> Absolute rate symbol: recovery #> [[4]] #> From: I #> To: D #> Per-capita rate expression: p * gamma #> Absolute rate symbol: death"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"the-change_frame-method","dir":"Articles","previous_headings":"Internal Design > ChangeComponent() classes","what":"The change_frame() method","title":"ODE Solvers, Process Error, and Difference Equations","text":"Returns data frame two columns: * state : state variable changed (.e. updated step) * change : signed absolute flow rates (variables expressions don’t involve state variables) example data frame flow S follows. simple Formula change component data frame just empty two-column data frame zero rows.","code":"cc[[2]]$change_frame() #>   state     change #> 1     S -infection #> 2     I +infection cc[[1]]$change_frame() #> [1] state  change #> <0 rows> (or 0-length row.names)"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"the-flow_frame-method","dir":"Articles","previous_headings":"Internal Design > ChangeComponent() classes","what":"The flow_frame() method","title":"ODE Solvers, Process Error, and Difference Equations","text":"Returns data frame three columns. * size : variable (often state variable function state variables) gives size population drawn flow (e.g. S size infection flow). * change : unsigned absolute flow rates. * rate : per-capita flow rates (variables expresions sometimes involve state variables). example data frame flow S follows. simple Formula change component data frame just empty three-column data frame zero rows.","code":"cc[[2]]$flow_frame() #>   size    change       rate         abs_rate #> 1    S infection beta * I/N S * (beta * I/N) cc[[1]]$flow_frame() #> [1] size     change   rate     abs_rate #> <0 rows> (or 0-length row.names)"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"changemodel-classes","dir":"Articles","previous_headings":"Internal Design","what":"ChangeModel() classes","title":"ODE Solvers, Process Error, and Difference Equations","text":"ChangeModel objects combine information lists ChangeComponent objects, specify full model. expands concept , , refined set steps. methods return lists two-sided formulas. before_loop() : list formulas. once_start() : Formulas evaluate start list, repeated (modified repeated) throughout expansions loop. example expansion Runge-Kutta differential equation solver reuses expressions iterative manner. Formulas returned once_during() useful specifying exogeneous changes (e.g., time-varying parameters) occur per time-step change throughout within-time-step iterations differential equation solver. before_flows() : Formulas evaluate absolute flow rates computed. update_flows() : Formulas update flows, using flow_frame() methods individual ChangeComponent objects. before_state() : Formulas evaluate state vector updated. update_state() : Formulas update state vector, using change_frame() method s individual ChangeComponent objects. after_state() : Formulas evaluate state vector updated. once_end() : Formulas evaluate end list, repeated throughout (similar once_start()). after_loop() : list formulas. ChangeModel objects also flow_frame() change_frame() methods combining outputs methods within individual ChangeComponent objects. example SIR model gives flow_frame() change_frame() output follows. update_flows() method update_state() method makes use flow_frame() produce ","code":"state   change -----   ------ S       -infection I       +infection I       -recovery R       +recovery size  change     rate ----  ------     ---- S     infection  beta * I / N I     recovery   gamma si = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") si$change_model #> Classes 'SimpleChangeModel', 'ChangeModelDefaults', 'ChangeModel', 'Base' <environment: 0x555d01240008>  #> after_loop : function ()   #> after_state : function ()   #> all_user_aware_names : function ()   #> before_flows : function ()   #> before_loop : function ()   #> before_state : function ()   #> change_classes : function ()   #> change_frame : function ()   #> flow_frame : function ()   #> no_change_components : function ()   #> once_finish : function ()   #> once_start : function ()   #> other_generated_formulas : function ()   #> update_flows : function ()   #> update_state : function ()   #> user_formulas : function () si$change_model$flow_frame() #>   size    change       rate         abs_rate #> 1    S infection I * beta/N S * (I * beta/N) #> 2    I  recovery      gamma      I * (gamma) si$change_model$change_frame() #>   state     change #> 1     S -infection #> 2     I +infection #> 3     I  -recovery #> 4     R  +recovery si$change_model$update_state() #> [[1]] #> S ~ -infection #> <environment: 0x555d0064f388> #>  #> [[2]] #> I ~ +infection - recovery #> <environment: 0x555d0064f388> #>  #> [[3]] #> R ~ +recovery #> <environment: 0x555d0064f388> si$change_model$update_flows() #> $S #> $S[[1]] #> infection ~ I * beta/N #> <environment: 0x555d007014d0> #>  #>  #> $I #> $I[[1]] #> recovery ~ gamma #> <environment: 0x555d007014d0> spec = mp_tmb_model_spec(   during = list(       mp_per_capita_flow(\"A\", \"B\", \"a\", \"r\")     , mp_per_capita_flow(\"B\", \"C\", \"b\", \"rr\")   ) ) spec$change_model$update_flows() #> $A #> $A[[1]] #> r ~ a #> <environment: 0x555cf7fc4328> #>  #>  #> $B #> $B[[1]] #> rr ~ b #> <environment: 0x555cf7fc4328>"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"updatemethod-classes","dir":"Articles","previous_headings":"Internal Design","what":"UpdateMethod() classes","title":"ODE Solvers, Process Error, and Difference Equations","text":"order define state updater one must define new UpdateMethod class. classes required update three methods take arguments: , , . methods required return list two-sided formulas giving expression list three phases simulation: simulation loop, every iteration simulation loop, simulation loop. Examples UpdateMethod classes include: EulerUpdateMethod, RK4UpdateMethod, EulerMultinomialUpdateMethod, HazardUpdateMethod. constructors UpdateMethod classes often field class ChangeModel, specifies sort components ","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"relationship-to-ordinary-differential-equation-solvers","dir":"Articles","previous_headings":"","what":"Relationship to Ordinary Differential Equation Solvers","title":"ODE Solvers, Process Error, and Difference Equations","text":"instructive view state update methods approximate solutions ordinary differential equations (ODEs). consider ODEs following form. dxidt=∑jxjrji⏟inflow−∑jxirij⏟outflow \\frac{dx_i}{dt} = \\underbrace{\\sum_j x_j r_{ji}}_{\\text{inflow}} - \\underbrace{\\sum_j x_i r_{ij}}_{\\text{outflow}}  per-capita rate flowing compartment ii compartment jj rijr_{ij}, xix_i number individuals iith compartment. allow rijr_{ij} depend number state variables time-varying parameters. example, SIR model xS,xI,xRx_S, x_I, x_R (readability use S,,RS, , R). case rSI=βI/Nr_{SI} = \\beta / N, rIR=γr_{IR} = \\gamma, values rijr_{ij} zero. force infection, rSIr_{SI}, depends state variable II. Although state-update method presented can thought approximate solution ODE, can also thought dynamical models right. example, Euler-multinomial model useful model process error.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"euler","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Euler","title":"ODE Solvers, Process Error, and Difference Equations","text":"simplest approach just pretend ODEs difference equations. case, time-step, state variable updated follows. xi=xi−∑jxirij+∑jxjrji x_i = x_i - \\sum_j x_i r_{ij} + \\sum_j x_j r_{ji}  SIR example follows. S=S−SrSI S = S - Sr_{SI} =−IrIR+SrSI = - Ir_{IR} + Sr_{SI} R=R+IrIR R = R + Ir_{IR}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"runge-kutta-4","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Runge Kutta 4","title":"ODE Solvers, Process Error, and Difference Equations","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"euler-multinomial","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Euler-Multinomial","title":"ODE Solvers, Process Error, and Difference Equations","text":"Euler-multinomial state update method assumes number individuals move one box another single time-step random non-negative integer, coming particular multinomial distribution now describe. probability staying iith box entire time-step assumed following (TODO: relate Poisson processes). pii=exp(−∑jrij) p_{ii} = \\exp\\left(-\\sum_j r_{ij}\\right) probability assumes rijr_{ij} held constant throughout entire time-step, although can change time-step begins. probability moving box ii box jj one time-step given following. pij=(1−pii)rij∑jrij p_{ij} = (1 - p_{ii}) \\frac{r_{ij}}{\\sum_j r_{ij}} probability just probability staying box ii, 1−pii1 - p_{ii}, specifically going box jj, assumed given expression rij∑jrij\\frac{r_{ij}}{\\sum_j r_{ij}}. Let ρij\\rho_{ij} random number individuals move box ii box jj one time-step. expected value ρij\\rho_{ij} pijxip_{ij} x_i. However, random variables independent events, total number individuals, ∑ixi\\sum_i x_i, remain constant single time-step (least models currently considering). account non-independence, collect ρij\\rho_{ij} associated compartment ii vector ρi\\rho_i. collect similar vector probabilities, pip_i. ρi\\rho_i random draw multinomial distribution xix_i trials probability vector, pip_i. random draws made, state variables can updated time-step follows. xi=xi−∑jρij+∑jρji x_i = x_i - \\sum_j \\rho_{ij} + \\sum_j \\rho_{ji} Note actually need generate values diagonal elements, ρii\\rho_{ii}, cancel update equation. also can ignore ρij\\rho_{ij} rij=0r_{ij} = 0. SIR example particularly simple Euler-binomial distribution branching flows – individuals leave S can go leave can go R. two flows given following distributions. ρSI∼Binomial(S,pSI) \\rho_{SI} \\sim \\text{Binomial}(S, p_{SI}) ρIR∼Binomial(,pIR) \\rho_{IR} \\sim \\text{Binomial}(, p_{IR}) models branching flows multinomial distributions. model state update given following equations. S=S−ρSI S = S - \\rho_{SI} =−ρIR+ρSI = - \\rho_{IR} + \\rho_{SI} R=R+ρIR R = R + \\rho_{IR}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"hazard","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Hazard","title":"ODE Solvers, Process Error, and Difference Equations","text":"Hazard update-method uses expected values associated Euler-multinomial described . particular, state variables updated follows. xi=xi−∑jxipij+∑jxjpji x_i = x_i - \\sum_j x_i p_{ij} + \\sum_j x_j p_{ji} SIR model follows. S=S−SpSI S = S - Sp_{SI} =−IpIR+SpSI = - Ip_{IR} + Sp_{SI} R=R+IpIR R = R + Ip_{IR} explicitly II compartment . (t+1)=(t)−(t)(1−exp(−γ))+S(t)(1−exp(−βI(t))) (t+1) = (t) - (t) (1 - \\exp(-\\gamma)) + S(t)(1 - \\exp(-\\beta (t)))","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"linearizing-at-each-time-step","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Linearizing at Each Time-Step","title":"ODE Solvers, Process Error, and Difference Equations","text":"rijr_{ij} depend state variable, ODE generally non-linear. However, linearize model every time-step explicitly compute matrix exponential find approximate state update.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"hazard-in-models-including-more-than-unbalanced-per-capita-flows","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Hazard in models including more than unbalanced per-capita flows","title":"ODE Solvers, Process Error, and Difference Equations","text":"perfectly balanced per-capita flows approach used always work. example, virus shedding wastewater compartment involve infected individuals flowing wastewater compartment, people become wastewater obviously. models need think clearly use Hazard approximation. cases can modify differential equation include arbitrary number absolute inflows outflows. dxidt=∑jxjrji⏟inflow−∑jxirij⏟outflow+∑krik+⏟absolute inflow−∑lril−⏟absolute outflow \\frac{dx_i}{dt} =      \\underbrace{\\sum_j x_j r_{ji}}_{\\text{inflow}}    - \\underbrace{\\sum_j x_i r_{ij}}_{\\text{outflow}}   + \\underbrace{\\sum_k r^+_{ik}}_{\\text{absolute inflow}}   - \\underbrace{\\sum_l r^-_{il}}_{\\text{absolute outflow}} rik+r^+_{ik} absolute rate xix_i increases due mechanism kk ril−r^-_{il} absolute rate xix_i decreases due mechanism ll.","code":""},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"baseline-sir-model","dir":"Articles","previous_headings":"","what":"Baseline SIR Model","title":"Specifying Time-Varying Parameters","text":"modify SIR model transmission rate time-varying. initialize vector state labels parameter default values convenience specify simulation time 50 time steps. Using fixed transmission rate 0.8 visualize baseline SIR dynamics.","code":"state_labels = c(\"S\", \"I\", \"R\") time_steps = 50 beta = 0.8 # per-capita transmission rate gamma = 0.2 # per-capita recovery rate"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"piecewise-time-variation","dir":"Articles","previous_headings":"","what":"Piecewise Time Variation","title":"Specifying Time-Varying Parameters","text":"create piecewise time-varying transmission rate, need specify two variables: beta_changepoints - integer vector containing starting time steps transmission rate beta changes. vector starts time step 0 want specify initial default value beta followed changing transmission rates beginning time-step 10 15. (Note: Currently macpan2::time_var expects argument change_points start 0, default value beta example used. future development, time_var accept change_points[1] > 0 use default value parameter time steps change_points[1]. See Update time_var incorporate default value) beta_values numeric vector containing values beta takes time step specified beta_changepoints. need specify expression updates beta beta_values time steps beta_changepoints. use time_var function return value beta, beta_values, comparing current time step time steps beta_changepoints. Let’s test time_var computing want 20 time steps. Now know expression updating beta correctly, can modify SIR model include piece-wise transmission rate. Now plot updated simulations using change-points, highlight vertical lines. clear changes dynamics times 10 15 due drop lift transmission rate time steps.","code":"beta_changepoints = c(0, 10, 15) beta_values = c(0.8, 0.01, 0.4) # see ?time_var for arguments expr = list(  beta ~ time_var(beta_values, beta_changepoints) ) simple_sims(     iteration_exprs = expr   , time_steps = 20      # for integer vectors (usually indexing vectors) use `int_vecs`   , int_vecs = list(beta_changepoints = beta_changepoints)      # for numeric vectors (model defaults) use `mats`   # we need to initialize beta because it is a variable in our model   # so we set to 0.8 - at the beginning of the simulation loop (time_step==1)   # beta gets updated so the initial value of beta has no effect in this case   , mats = list(       beta = beta     , beta_values = beta_values)  ) |> filter(matrix == \"beta\") #>    matrix time row col value #> 1    beta    1   0   0  0.80 #> 2    beta    2   0   0  0.80 #> 3    beta    3   0   0  0.80 #> 4    beta    4   0   0  0.80 #> 5    beta    5   0   0  0.80 #> 6    beta    6   0   0  0.80 #> 7    beta    7   0   0  0.80 #> 8    beta    8   0   0  0.80 #> 9    beta    9   0   0  0.80 #> 10   beta   10   0   0  0.01 #> 11   beta   11   0   0  0.01 #> 12   beta   12   0   0  0.01 #> 13   beta   13   0   0  0.01 #> 14   beta   14   0   0  0.01 #> 15   beta   15   0   0  0.40 #> 16   beta   16   0   0  0.40 #> 17   beta   17   0   0  0.40 #> 18   beta   18   0   0  0.40 #> 19   beta   19   0   0  0.40 #> 20   beta   20   0   0  0.40 # model specification with piece-wise transmission rates piecewise_spec = (   \"starter_models\"   # read in model from library                       |> mp_tmb_library(\"sir\", package = \"macpan2\")   # insert expression for updating beta at the beginning of the simulation loop   |> mp_tmb_insert(       phase=\"during\"     , at=1     , expressions = expr     , default = list(         # Note: the default value of beta here has no effect, because at the         # first time step beta is updated to beta_values[1]         beta = beta       , gamma = gamma       , beta_values = beta_values       )     , integers = list(beta_changepoints = beta_changepoints)) ) # check that model spec was updated accordingly print(piecewise_spec) #> --------------------- #> Default values: #> --------------------- #>       matrix row col value #>         beta         8e-01 #>        gamma         2e-01 #>            N         1e+02 #>            I         1e+00 #>            R         0e+00 #>  beta_values   0     8e-01 #>  beta_values   1     1e-02 #>  beta_values   2     4e-01 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: beta ~ time_var(beta_values, beta_changepoints) #> 2: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 3: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)  # create simulator object piecewise_simulator = (piecewise_spec    |> mp_simulator(time_steps = time_steps, outputs=c(state_labels))  )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"calibrating-time-variation-parameters","dir":"Articles","previous_headings":"","what":"Calibrating Time Variation Parameters","title":"Specifying Time-Varying Parameters","text":"First simulate data fit model , see can recover time-varying parameters.  often want include parameter constraints models, one way implicitly transform parameters (Bolker 2008). , transformations can sometimes help estimating parameters making “likelihood surface closer quadratic” reducing parameter correlation (Bolker 2008). log-transform β\\beta constraint β\\beta must positive domain logarithm (0,∞)(0, \\infty). Next create calibrator object specify want estimate vector time varying transmission rates, log_beta_values, passing parameter name par argument. optimizing, can make coefficient plot estimated values confidence intervals, compare true values.  general, transmission rate estimates follow expected pattern changing high, low, moderate. precise estimate, true value 0.8, results observed prevalence data informative transmission rate infection initially spreading. makes sense get accurate estimate final transmission rate observed data simulated final known transmission rate. lose accuracy precision middle rate 5 time steps observed data informing parameter.","code":"set.seed(1L) I_observed = (sim_data               |> filter(matrix==\"I\")               # add some poisson noise               |> mutate(value = rpois(n(),value)) ) plot(I_observed$time, I_observed$value) # transformed model specification transformed_spec = mp_tmb_insert(     model = piecewise_spec   , phase = \"before\"   , at = 1   # we need to exponentiate log transformed values so beta is on the appropriate   # scale when computing model dynamics   , expressions = list(beta_values ~ exp(log_beta_values))   # we also need to specify default values for log_beta_values   # here we set all default values for beta to the mean of the true values   # i.e. mean(log(beta_values))   , default = list(       log_beta_values = rep(mean(log(beta_values)), length(beta_values))     ) ) # Note the true values of beta (`beta_values`) are still included in the default # list, however they get updated before the simulation loop, so they are not # informing our estimates for these values when calibrating. transformed_spec #> --------------------- #> Default values: #> --------------------- #>           matrix row col      value #>             beta           0.800000 #>            gamma           0.200000 #>                N         100.000000 #>                I           1.000000 #>                R           0.000000 #>      beta_values   0       0.800000 #>      beta_values   1       0.010000 #>      beta_values   2       0.400000 #>  log_beta_values   0      -1.914868 #>  log_beta_values   1      -1.914868 #>  log_beta_values   2      -1.914868 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: beta_values ~ exp(log_beta_values) #> 2: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: beta ~ time_var(beta_values, beta_changepoints) #> 2: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 3: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) # set up calibrator object piecewise_calib = mp_tmb_calibrator(     spec = transformed_spec   , data = I_observed   , traj = \"I\"   # we want to estimate the log-transformed parameters   , par = \"log_beta_values\"   , outputs = state_labels )  # optimization step mp_optimize(piecewise_calib) #> outer mgc:  486.7233 #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> outer mgc:  699.5397  #> outer mgc:  148.8469  #> outer mgc:  190.1806  #> outer mgc:  118.6255  #> outer mgc:  48.17214  #> outer mgc:  3.120084  #> outer mgc:  0.5353311  #> outer mgc:  0.01025667  #> outer mgc:  1.863369e-05  #> outer mgc:  3.959838e-11 #> $par #>     params     params     params  #> -0.2144229 -2.8405257 -0.8566479  #>  #> $objective #> [1] 94.85064 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 10 #>  #> $evaluations #> function gradient  #>       14       11  #>  #> $message #> [1] \"relative convergence (4)\""},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"radial-basis-functions-for-flexible-time-variation-in-progress","dir":"Articles","previous_headings":"","what":"Radial Basis Functions for Flexible Time Variation (In-Progress)","title":"Specifying Time-Varying Parameters","text":"section uses radial basis functions (RBFs) generate models flexible functional form smooth changes transmission rate. can add fancy radial basis transmission rate, need base model. use SIR model modified include waning. macpan2::rbf function can used produce matrix giving values basis function (column) time step (row). Using matrix, XX, weights vector, bb, can get flexible output vector, yy, shape can modified changing weights vector. y=Xb y = Xb following code illustrates approach.  d dimension basis, number functions, n number time steps. multiplying uniform basis matrix (top panel) set weights (middle panel), obtain non-uniform curve (bottom panel). Note peaks (troughs) output associated large positive (negative) weights. Now want transform output (matrix) product RBF matrix weights vector time-series transmission rate, β\\beta. Although just use output vector β\\beta time series, convenient transform β\\beta values yield interesting dynamics SIR model. particular, model βt\\beta_t function time, tt, log(βt)=log(γt)+log(N)−log(St)+xtb \\log(\\beta_t) = \\log(\\gamma_t) + \\log(N) - \\log(S_t) + x_tb recovery rate, γt\\gamma_t, number susceptibles, StS_t, time, tt, total population, NN, ttth row XX, xtx_t. better understand rationale equation note every element bb set zero, following condition. βtStN=γt \\frac{\\beta_t S_t}{N} = \\gamma_t condition assures number infected individuals remains constant time, tt. means positive values bb tend generate outbreaks negative values tend reduce transmission. fixme: (BMB) understand ’re setting model way, ’s odd/non-standard setup - may confuse people already familiar epidemic models (confused initially). simulation model radial basis exogenous transmission rate dynamics.","code":"sir_waning = mp_tmb_library(\"starter_models\"   , \"sir_waning\"   , package = \"macpan2\" ) set.seed(1L) d = 20 n = 2500 X = rbf(n, d) b = rnorm(d, sd = 0.01) par(mfrow = c(3, 1)   , mar = c(0.5, 4, 1, 1) + 0.1 ) matplot(X   , type = \"l\", lty = 1, col = 1   , ylab = \"basis functions\"   , axes = FALSE ) axis(side = 2) box() barplot(b   , xlab = \"\"   , ylab = \"weights\" ) par(mar = c(5, 4, 1, 1) + 0.1) plot(X %*% b   , type = \"l\"   , xlab = \"time\"   , ylab = \"output\" ) set.seed(1L)  spec_waning = (sir_waning              |> mp_tmb_insert(                  phase = \"before\"                , at = Inf                , expressions = list(eta ~ gamma * exp(X %*% b))                , default = list(eta = empty_matrix, X = X, b = b)              ) |> mp_tmb_insert(                  phase = \"during\"                , at = 1                , expressions = list(beta  ~ eta[time_step(1)] / clamp(S/N, 1/100))              ) )   simulator_waning = (spec_waning   |> mp_simulator(     time_steps = n   , outputs = c(\"S\", \"I\", \"R\", \"infection\", \"beta\")   , default = list(       N = 100000, I = 500, R = 0     , beta = 1, gamma = 0.2, phi = 0.01    )) )   print(simulator_waning) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #> 2: eta ~ gamma * exp(X %*% b) #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to 2500): #> --------------------- #> 1: beta ~ eta[time_step(1)]/clamp(S/N, 1/100) #> 2: infection ~ S * (I * beta/N) #> 3: recovery ~ I * (gamma) #> 4: waning_immunity ~ R * (phi) #> 5: S ~ S - infection + waning_immunity #> 6: I ~ I + infection - recovery #> 7: R ~ R + recovery - waning_immunity (simulator_waning  |> mp_trajectory()  |> ggplot()  + facet_wrap(~ matrix, ncol = 1, scales = 'free')  + geom_line(aes(time, value)) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"calibration","dir":"Articles","previous_headings":"Radial Basis Functions for Flexible Time Variation (In-Progress)","what":"Calibration","title":"Specifying Time-Varying Parameters","text":"can perform calibration time-varying parameter specified radial basis, using function macpan2::mp_rbf(). follow ususal steps calibration. 1. Simulate model add poisson noise: 2. Add calibration information. 3. Review results. fit observed data looks reasonable, however obvious wiggly deviations.","code":"obs_rbf = (simulator_waning  |> mp_trajectory()  |> filter(matrix==\"I\")  |> mutate(across(value, ~ rpois(n(), .))) ) calib_rbf = mp_tmb_calibrator(sir_waning    , data = obs_rbf    , traj = \"I\"    ## estimate     , par = \"beta\"    , tv = mp_rbf(\"beta\", dimension = d, initial_weights = b)    ## pass all defaults, including dimension of the rbf `d` and initial weights vector `b`    , default = list(N = 100000, I = 500, R = 0, beta = 1, gamma = 0.2, phi = 0.01, d = d, b = b)     )    mp_optimize(calib_rbf) #> outer mgc:  260404.5  #> outer mgc:  516278.6  #> outer mgc:  587174.9  #> outer mgc:  650089  #> outer mgc:  551580.4  #> outer mgc:  577141  #> outer mgc:  544591  #> outer mgc:  343582.7  #> outer mgc:  219354.8  #> outer mgc:  474385.6  #> outer mgc:  759175.8  #> outer mgc:  1981896  #> outer mgc:  572674.8  #> outer mgc:  130718.1  #> outer mgc:  11623.46  #> outer mgc:  2573.963  #> outer mgc:  250.8778  #> outer mgc:  3.075834  #> outer mgc:  0.0004771355 #> $par #>      params      params      params      params      params      params  #> -1.27641280 -0.23972069 -0.88918700 -0.48246900 -0.71662892 -0.54489211  #>      params      params      params      params      params      params  #> -0.66403205 -0.55987089 -0.60953016 -0.48826067 -0.53743851 -0.35883656  #>      params      params      params      params      params      params  #>  0.01438706 -0.51734442 -0.50528656 -0.51390784 -0.56715449 -0.36571049  #>      params      params      params  #> -0.67953264  0.38050808  0.55256296  #>  #> $objective #> [1] 30057.53 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 19 #>  #> $evaluations #> function gradient  #>       32       19  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" ## check estimates mp_tmb_coef(calib_rbf,conf.int = TRUE) #> outer mgc:  0.0004771355  #> outer mgc:  10106.35  #> outer mgc:  10244.65  #> outer mgc:  18039.69  #> outer mgc:  18377.17  #> outer mgc:  17661.5  #> outer mgc:  18052.09  #> outer mgc:  17007.5  #> outer mgc:  17390.3  #> outer mgc:  12227.71  #> outer mgc:  12481.76  #> outer mgc:  9350.09  #> outer mgc:  9523.219  #> outer mgc:  8689.409  #> outer mgc:  8849.081  #> outer mgc:  7212.485  #> outer mgc:  7337.635  #> outer mgc:  4499.09  #> outer mgc:  4557.787  #> outer mgc:  2639.332  #> outer mgc:  2663.877  #> outer mgc:  1474.115  #> outer mgc:  1484.504  #> outer mgc:  630.3664  #> outer mgc:  632.9975  #> outer mgc:  367.2692  #> outer mgc:  368.5147  #> outer mgc:  926.993  #> outer mgc:  932.217  #> outer mgc:  2072.398  #> outer mgc:  2092.068  #> outer mgc:  2411.296  #> outer mgc:  2433.905  #> outer mgc:  2161.669  #> outer mgc:  2180.24  #> outer mgc:  1396.096  #> outer mgc:  1405.354  #> outer mgc:  696.5062  #> outer mgc:  699.8151  #> outer mgc:  211.0486  #> outer mgc:  211.5534  #> outer mgc:  89.26982  #> outer mgc:  90.08222  #> outer mgc:  7442.986 #>         term           mat row col       default  type    estimate   std.error #> 1     params time_var_beta   0   0 -0.0062645381 fixed -1.27641280 0.001463832 #> 2   params.1 time_var_beta   1   0  0.0018364332 fixed -0.23972069 0.001977560 #> 3  params.10 time_var_beta  10   0  0.0151178117 fixed -0.53743851 0.002792037 #> 4  params.11 time_var_beta  11   0  0.0038984324 fixed -0.35883656 0.003704611 #> 5  params.12 time_var_beta  12   0 -0.0062124058 fixed  0.01438706 0.004098547 #> 6  params.13 time_var_beta  13   0 -0.0221469989 fixed -0.51734442 0.003224495 #> 7  params.14 time_var_beta  14   0  0.0112493092 fixed -0.50528656 0.002548279 #> 8  params.15 time_var_beta  15   0 -0.0004493361 fixed -0.51390784 0.002403806 #> 9  params.16 time_var_beta  16   0 -0.0001619026 fixed -0.56715449 0.002599612 #> 10 params.17 time_var_beta  17   0  0.0094383621 fixed -0.36571049 0.003240611 #> 11 params.18 time_var_beta  18   0  0.0082122120 fixed -0.67953264 0.004104058 #> 12 params.19 time_var_beta  19   0  0.0059390132 fixed  0.38050808 0.004919260 #> 13  params.2 time_var_beta   2   0 -0.0083562861 fixed -0.88918700 0.002074339 #> 14 params.20 prior_sd_beta   0   0  1.0000000000 fixed  0.55256296 0.003339349 #> 15  params.3 time_var_beta   3   0  0.0159528080 fixed -0.48246900 0.001927518 #> 16  params.4 time_var_beta   4   0  0.0032950777 fixed -0.71662892 0.001755581 #> 17  params.5 time_var_beta   5   0 -0.0082046838 fixed -0.54489211 0.001597672 #> 18  params.6 time_var_beta   6   0  0.0048742905 fixed -0.66403205 0.001506794 #> 19  params.7 time_var_beta   7   0  0.0073832471 fixed -0.55987089 0.001518645 #> 20  params.8 time_var_beta   8   0  0.0057578135 fixed -0.60953016 0.001727385 #> 21  params.9 time_var_beta   9   0 -0.0030538839 fixed -0.48826067 0.002143931 #>        conf.low   conf.high #> 1  -1.279281858 -1.27354374 #> 2  -0.243596641 -0.23584475 #> 3  -0.542910801 -0.53196622 #> 4  -0.366097459 -0.35157565 #> 5   0.006354052  0.02242006 #> 6  -0.523664313 -0.51102453 #> 7  -0.510281099 -0.50029203 #> 8  -0.518619216 -0.50919647 #> 9  -0.572249636 -0.56205934 #> 10 -0.372061971 -0.35935901 #> 11 -0.687576449 -0.67148884 #> 12  0.370866505  0.39014965 #> 13 -0.893252629 -0.88512137 #> 14  0.546017957  0.55910797 #> 15 -0.486246869 -0.47869114 #> 16 -0.720069797 -0.71318804 #> 17 -0.548023491 -0.54176073 #> 18 -0.666985316 -0.66107879 #> 19 -0.562847379 -0.55689440 #> 20 -0.612915777 -0.60614455 #> 21 -0.492462697 -0.48405864"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"baseline-sir-model","dir":"Articles","previous_headings":"","what":"Baseline SIR Model","title":"Advanced Specification of Time-Varying Parameters","text":"modify SIR model transmission rate time-varying.","code":"state_labels = c(\"S\", \"I\", \"R\") simulator = (\"starter_models\"   |> mp_tmb_library(\"sir\", package = \"macpan2\")   |> mp_simulator(time_steps = 50     , outputs = state_labels     , default = list(beta = 0.8, gamma = 0.2)   ) ) (simulator   |> mp_trajectory()   |> mutate(state = factor(matrix, state_labels))   |> ggplot()    + geom_line(aes(time, value, colour = state)) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"piecewise-time-variation","dir":"Articles","previous_headings":"","what":"Piecewise Time Variation","title":"Advanced Specification of Time-Varying Parameters","text":"now change value transmission rate, beta, beginning time-step 10 15. first step add simulator vector containing change-points. Next add values beta changes time-steps. also need variable track current value beta. beta_pointer starts time-step equal 0, incremented throughout simulation. increment beta_pointer using time_group function returns either beta_pointer beta_pointer + 1 depending whether current time-step change-point beta_changepoints. update beta every iteration simulation loop using beta_pointer. Now plot updated simulations using change-points, highlight vertical lines.  clear kinks times 10 15 due drop lift transmission rate times.","code":"simulator$add$matrices(beta_changepoints = c(0, 10, 15)) simulator$add$matrices(beta_values = c(0.8, 0.01, 0.4)) simulator$add$matrices(beta_pointer = 0) simulator$insert$expressions(     beta_pointer ~ time_group(beta_pointer, beta_changepoints),      .phase = \"during\" ) simulator$insert$expressions(   beta ~ beta_values[beta_pointer],   .phase = \"during\" ) s = mp_trajectory(simulator) cp = simulator$get$initial(\"beta_changepoints\") (s   %>% mutate(state = factor(matrix, state_labels))   %>% ggplot()   + geom_line(aes(time, value, colour = state))   + geom_vline(     aes(xintercept = x),      linetype = \"dashed\",      alpha = 0.5,      data = data.frame(x = cp)   ) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"calibrating-time-variation-parameters","dir":"Articles","previous_headings":"","what":"Calibrating Time Variation Parameters","title":"Advanced Specification of Time-Varying Parameters","text":"First simulate data fit model , see can recover time-varying parameters.  add matrices model keeping tracking information used model fitting. Now need new expressions. first expression pulls state state vector. second expression computes vector Poisson log-likelihood values – one time step. Next declare beta values parameters optimized log scale. clearest way form data frame one row parameter fitted. couple potentially confusing aspects data frame. First, want fit beta values log scale, indicate prepending log_ front name beta_values matrix model. explicitly add log_beta_values matrix model next code chunk. Second, word row corresponds index change points. particular, row = 0 corresponds initial beta, row = 1 first change point row = 2 second. quantities passed macpan2 engines matrices, case different rows log_beta_values matrix (actually column vector) correspond different change points. dealing matrices one column need include col column data frame indicate matrix columns matrix entries correspond parameters fitted. Now log transform beta_values matrix entries declare parameters. Finally fit model back simulation data. can see optimizer converges (.e. $convergence = 0) 26 iterations. log scale see optimizer finds different values (current) started (default). importantly beta values untransformed scale recover reasonable values qualitatively consistent values used simulations. Note however second fitted beta value much smaller true value, potentially interesting.","code":"set.seed(1L) I_observed = rpois(50   , filter(s, matrix == \"I\")$value ) plot(I_observed) simulator$update$matrices(      ## observed data   I_obs = I_observed,      ## simulated trajectory to compare with data   I_sim = empty_matrix,       ## location of I in the state vector   ## (the `-1L` bit is to get 0-based indices instead of 1-based)   I_index = match(\"I\", state_labels) - 1L,       ## matrix to contain the log likelihood values at    ## each time step   log_lik = empty_matrix,       ## need to save the simulation history of each of these matrices   .mats_to_save = c(\"I_sim\", \"log_lik\") ) simulator$insert$expressions(   I_sim ~ I,   .phase = \"during\" ) simulator$insert$expressions(   log_lik ~ dpois(I_obs, clamp(rbind_time(I_sim))),   .phase = \"after\" ) simulator$replace$obj_fn(~ -sum(log_lik)) default_beta = mean(simulator$get$initial(\"beta_values\")) params_to_fit = data.frame(     mat = \"log_beta_values\"   , row = 0:2   , default = log(default_beta) ) print(params_to_fit) #>               mat row    default #> 1 log_beta_values   0 -0.9079919 #> 2 log_beta_values   1 -0.9079919 #> 3 log_beta_values   2 -0.9079919 simulator$add$transformations(Log(\"beta_values\")) simulator$replace$params_frame(params_to_fit) simulator$optimize$nlminb() #> outer mgc:  736.1414  #> outer mgc:  112.6655  #> outer mgc:  71.38648  #> outer mgc:  13.6616  #> outer mgc:  12.58091  #> outer mgc:  3.638083  #> outer mgc:  1.399513  #> outer mgc:  1.609453  #> outer mgc:  1.140347  #> outer mgc:  0.5870909  #> outer mgc:  0.2527136  #> outer mgc:  0.09938628  #> outer mgc:  0.03753935  #> outer mgc:  0.01394885  #> outer mgc:  0.005150654  #> outer mgc:  0.001897432  #> outer mgc:  0.0006983805  #> outer mgc:  0.0002569678  #> outer mgc:  9.453968e-05  #> outer mgc:  3.478009e-05  #> outer mgc:  1.2795e-05  #> outer mgc:  4.707033e-06  #> outer mgc:  1.731623e-06  #> outer mgc:  6.370285e-07  #> outer mgc:  2.343501e-07  #> outer mgc:  8.621238e-08  #> outer mgc:  3.171574e-08 #> $par #>      params      params      params  #>  -0.1710158 -22.8268369  -0.8291142  #>  #> $objective #> [1] 99.74231 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 26 #>  #> $evaluations #> function gradient  #>       28       27  #>  #> $message #> [1] \"relative convergence (4)\" simulator$current$params_frame() #>   par_id             mat row col    default     current #> 1      0 log_beta_values   0   0 -0.9079919  -0.1710158 #> 2      1 log_beta_values   1   0 -0.9079919 -22.8268369 #> 3      2 log_beta_values   2   0 -0.9079919  -0.8291142 data.frame(   fitted = formatC(     exp(simulator$current$params_frame()$current),     format = \"e\", digits = 2   ),   true = simulator$get$initial(\"beta_values\") ) #>     fitted true #> 1 8.43e-01 0.80 #> 2 1.22e-10 0.01 #> 3 4.36e-01 0.40"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"radial-basis-functions-for-flexible-time-variation-in-progress","dir":"Articles","previous_headings":"","what":"Radial Basis Functions for Flexible Time Variation (In-Progress)","title":"Advanced Specification of Time-Varying Parameters","text":"section uses radial basis functions (RBFs) generate models flexible functional form smooth changes transmission rate. can add fancy radial basis transmission rate, need base model. use SIR model modified include waning. macpan2::rbf function can used produce matrix giving values basis function (column) time step (row). Using matrix, XX, weights vector, bb, can get flexible output vector, yy, shape can modified changing weights vector. y=Xb y = Xb following code illustrates approach.  d dimension basis, number functions, n number time steps. multiplying uniform basis matrix (top panel) set weights (middle panel), obtain non-uniform curve (bottom panel). Note peaks (troughs) output associated large positive (negative) weights. Now want transform output (matrix) product RBF matrix weights vector time-series transmission rate, β\\beta. Although just use output vector β\\beta time series, convenient transform β\\beta values yield interesting dynamics SIR model. particular, model βt\\beta_t function time, tt, log(βt)=log(γt)+log(N)−log(St)+xtb \\log(\\beta_t) = \\log(\\gamma_t) + \\log(N) - \\log(S_t) + x_tb recovery rate, γt\\gamma_t, number susceptibles, StS_t, time, tt, total population, NN, ttth row XX, xtx_t. better understand rationale equation note every element bb set zero, following condition. βtStN=γt \\frac{\\beta_t S_t}{N} = \\gamma_t condition assures number infected individuals remains constant time, tt. means positive values bb tend generate outbreaks negative values tend reduce transmission. fixme: (BMB) understand ’re setting model way, ’s odd/non-standard setup - may confuse people already familiar epidemic models (confused initially). simulation model radial basis exogenous transmission rate dynamics.","code":"sir = mp_tmb_library(\"starter_models\"   , \"sir_waning\"   , package = \"macpan2\" ) set.seed(1L) d = 20 n = 2500 X = rbf(n, d) b = rnorm(d, sd = 0.01) par(mfrow = c(3, 1)   , mar = c(0.5, 4, 1, 1) + 0.1 ) matplot(X   , type = \"l\", lty = 1, col = 1   , ylab = \"basis functions\"   , axes = FALSE ) axis(side = 2) box() barplot(b   , xlab = \"\"   , ylab = \"weights\" ) par(mar = c(5, 4, 1, 1) + 0.1) plot(X %*% b   , type = \"l\"   , xlab = \"time\"   , ylab = \"output\" ) set.seed(1L) simulator = mp_simulator(sir   , time_steps = n   , outputs = c(\"S\", \"I\", \"R\", \"infection\", \"beta\")   , default = list(       N = 100000, I = 500, R = 0     , beta = 1, gamma = 0.2, phi = 0.01     , X = rbf(n, d)     , b = rnorm(d, sd = 0.01)   ) ) simulator$insert$expressions(     eta ~ gamma * exp(X %*% b)   , .phase = \"before\"   , .at = Inf ) simulator$insert$expressions(     beta ~ eta[time_step(1)] / clamp(S/N, 1/100)   , .phase = \"during\"   , .at = 1 ) simulator$add$matrices(     eta = empty_matrix ) simulator$replace$params(     default = rnorm(d, sd = 0.01)   , mat = rep(\"b\", d)   , row = seq_len(d) - 1L ) print(simulator) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #> 2: eta ~ gamma * exp(X %*% b) #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to 2500): #> --------------------- #> 1: beta ~ eta[time_step(1)]/clamp(S/N, 1/100) #> 2: infection ~ S * (I * beta/N) #> 3: recovery ~ I * (gamma) #> 4: waning_immunity ~ R * (phi) #> 5: S ~ S - infection + waning_immunity #> 6: I ~ I + infection - recovery #> 7: R ~ R + recovery - waning_immunity (simulator  |> mp_trajectory()  |> ggplot()  + facet_wrap(~ matrix, ncol = 1, scales = 'free')  + geom_line(aes(time, value)) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"calibration","dir":"Articles","previous_headings":"Radial Basis Functions for Flexible Time Variation (In-Progress)","what":"Calibration","title":"Advanced Specification of Time-Varying Parameters","text":"Now ’re going calibrate model data. main innovation use built-feature TMB (macpan2 constructed), estimation latent variables Laplace approximation fit time series efficiently without overfitting (see section 5.10 Madsen Thyregod (2011), Kristensen et al. (2016), TMB documentation detail). next steps roughly follow first example Calibration vignette: TODO: make sure line state specific code calibration vignette. 1. Simulate model add noise:  2. Add calibration information. start adding standard boilerplate stuff include observed data store/return results. Now start deviate previous example: addition parameter (I_sd) standard deviation noise II, also add parameter (rbf_sd) variance RBF coefficients, penalize likelihood using Iobs∼Normal(Isim(ϕ,𝐛),σI2)bi∼Normal(0,σrbf2) \\begin{split} I_{\\textrm{obs}} & \\sim \\textrm{Normal}(I_\\textrm{sim}(\\phi, {\\mathbf b}), \\sigma^2_I) \\\\ b_i & \\sim \\textrm{Normal}(0, \\sigma^2_{\\textrm{rbf}}) \\end{split}  likelihood defined : $$ \\int {\\cal L}(I_{\\textrm{obs}}|\\phi, {\\mathbf b}', \\sigma^2_I) \\cdot {\\cal L}({\\mathbf b}'|\\sigma^2_{\\textrm{rbf}}) \\, d{\\mathbf b}. $$ ϕ\\phi vector set fixed-effect (unpenalized) parameters; case empty, include (example) time-constant recovery immune-waning rates, baseline transmission rate (see note ). (fixed-effect parameter usually denoted β\\beta statistical models, ’ve already used symbol transmission coefficient …) Although looks awful, (1) high-dimensional integral 𝐛\\mathbf b can separated product one-dimensional integrals (2) Laplace approximation gives us quick, reasonable approximation one-dimensional integrals. rbf_sd parameter can interpreted standard deviation Gaussian random effect approximately 1/λ1/\\sqrt{\\lambda} λ\\lambda ridge penalty. Continuing coding, add parameters negative log-likelihood model, making negative log-likelihood sum two terms integral : NLL data (-sum(dnorm(I_obs, ...))) likelihood RBF parameters (-sum(dnorm(b, ...))): fit SD parameters log scale. Finally, add b vector set random parameters: tells macpan2 apply Laplace approximation parameters … Test objective function: fixme: can’t get objective function shut . specified silent = TRUE calling MakeADFun() initially, now tried assigning value several different environments, without success … step normally produces lots output (output model random effects) Laplace approximation involves additional “inner” step b parameters optimized, even though evaluating objective single set fixed parameters (log_I_sd, log_rbf_sd) fixme: note developers, cache results may need call $retape() function restore internal structure retrieving … fixme: need incantation extract full parameters (including RE parameters) order make sure $report works properly? (general, caution mutability/make sure use last.par.best internally …) Extract parameters, run simulator best-fit parameters, compare data …  fixme: artificialities example /relaxed fixed parameters standard deviations. Normally also estimating gamma (possibly prior? examples, say calibration vignette, adding priors?) RBF function penalized zero. general, augment penalized RBF component (determines variation around mean) unpenalized intercept/baseline transmission parameter. , example, transmission rate computed b0 + exp(X %*% b), b0 represents unpenalized parameter ’s allowed vary freely … fixme: compare (1) unpenalized fit; (2) penalized fit without Laplace approximation … fixme: discuss (somewhere) alternate bases latent variables (random-walk, Gaussian process, …)","code":"obs_I <- (simulator     |> mp_trajectory()     |> filter(matrix == \"I\")     |> mutate(across(value, ~ rnorm(n(), ., sd = 50)))     |> pull(value) ) plot(obs_I, xlab = \"time\", ylab = \"prevalence\") ## copied from 'calibration/\"hello world\"' example simulator$add$matrices(     I_obs = obs_I   , I_sim = empty_matrix   , log_lik = empty_matrix   , .mats_to_save = c(\"I_sim\")   , .mats_to_return = c(\"I_sim\") ) simulator$insert$expressions(      I_sim ~ I    , .phase = \"during\"    , .at = Inf ) simulator$add$matrices(     I_sd = 1   , rbf_sd = 1 ) simulator$insert$expressions(      log_lik ~         -sum(dnorm(I_obs, rbind_time(I_sim), I_sd)) +        -1*sum(dnorm(b, 0.0, rbf_sd)),      .phase = \"after\" ) ## initially forgot this: maybe we could warn when someone is missing this???? simulator$replace$obj_fn(~ log_lik) simulator$add$transformations(Log(\"I_sd\")) simulator$add$transformations(Log(\"rbf_sd\")) ## not sure if this is required? params <- read.delim(sep = \"|\", header = TRUE,                      strip.white = TRUE, ## important!                       text = \" mat         | default log_I_sd    | 0 log_rbf_sd  | 1 \") simulator$replace$params_frame(params) matrix_version = \"1.6-5\" if (packageVersion(\"Matrix\") >= matrix_version) {   rparams <- data.frame(       mat  = \"b\",       row = 0:19,       col = 0,       default = 0)   simulator$replace$random_frame(rparams) } if (packageVersion(\"Matrix\") >= matrix_version) {   res <- simulator$ad_fun()$fn(c(1,1)) } #> iter: 1  value: 5994496 mgc: 2058657968 ustep: 1  #> iter: 2  value: 1327494 mgc: 1334286157 ustep: 1  #> iter: 3  value: 539106 mgc: 359174176 ustep: 1  #> iter: 4  value: 461675.4 mgc: 72820581 ustep: 1  #> iter: 5  value: 458020.4 mgc: 9231141 ustep: 1  #> iter: 6  value: 457980.9 mgc: 605743.9 ustep: 1  #> iter: 7  value: 457980.9 mgc: 7692.96 ustep: 1  #> iter: 8  value: 457980.9 mgc: 2.548908 ustep: 1  #> iter: 9  value: 457980.9 mgc: 1.89712e-06 ustep: 1  #> mgc: 8.929342e-07 #> [1] 458152.8 #> attr(,\"logarithm\") #> [1] TRUE if (packageVersion(\"Matrix\") >= matrix_version) {   ## testing: simulator$ad_fun()$fn()   fit <- simulator$optimize$nlminb() } if (packageVersion(\"Matrix\") >= matrix_version) {    ## simulator$print$matrix_dims()   ## fixed effects only:   ## look at parameters, but skip the random-effects parameters   ## 'random' holds the indices of the parameters that are treated   ## as random effects   (fixed_params <- with(simulator$ad_fun()$env,                         last.par.best[-random]))   ## ???   ## RE only   (ran_params <- with(simulator$ad_fun()$env,                       last.par.best[random])) } #>        random        random        random        random        random  #>  0.0067466350  0.0116662413 -0.0036351505 -0.0151989880  0.0011403827  #>        random        random        random        random        random  #>  0.0032615158 -0.0028962068 -0.0146686471 -0.0058110019  0.0073568463  #>        random        random        random        random        random  #>  0.0097221102  0.0023726453  0.0007574901  0.0014761570 -0.0134865091  #>        random        random        random        random        random  #> -0.0068787221 -0.0025147741  0.0027382985  0.0086679247  0.0033013692 if (packageVersion(\"Matrix\") >= matrix_version) {   pp <- simulator$ad_fun()$env$last.par.best  ## FIXME: use this   est_I <- (simulator       |> mp_trajectory()       |> filter(matrix == \"I\")       |> pull(value)   )   par(las = 1, bty = \"l\")   plot(obs_I, xlab = \"time\", ylab = \"prevalence\")   lines(est_I, col = 2, lwd = 2) }"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"stable","dir":"Articles","previous_headings":"","what":"Stable","title":"Article Status","text":"– Please read! Although mistakes always possible, please open issue find .","code":""},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"mature-draft","dir":"Articles","previous_headings":"","what":"Mature Draft","title":"Article Status","text":"– consistent accurate, yet widely utilized /checked correctness.","code":""},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"working-draft","dir":"Articles","previous_headings":"","what":"Working Draft","title":"Article Status","text":"– Makes sense, well inconsistent confusing.","code":""},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"stub","dir":"Articles","previous_headings":"","what":"Stub","title":"Article Status","text":"– even bother reading.","code":""},{"path":"https://canmod.github.io/macpan2/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Steve Walker. Maintainer, author. Weiguang Guan. Author. Jen Freeman. Author. Ben Bolker. Author. Darren Flynn-Primrose. Author. Irena Papst. Contributor. Michael Li. Contributor.","code":""},{"path":"https://canmod.github.io/macpan2/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Steve Walker, Weiguang Guan, Jen Freeman, Ben Bolker, Darren Flynn-Primrose (2024). macpan2: Fast Flexible Compartmental Modelling. R package version 1.11.0, https://github.com/canmod/macpan2, https://canmod.github.io/macpan2/.","code":"@Manual{,   title = {macpan2: Fast and Flexible Compartmental Modelling},   author = {{Steve Walker} and {Weiguang Guan} and {Jen Freeman} and {Ben Bolker} and {Darren Flynn-Primrose}},   year = {2024},   note = {R package version 1.11.0, https://github.com/canmod/macpan2},   url = {https://canmod.github.io/macpan2/}, }"},{"path":"https://canmod.github.io/macpan2/index.html","id":"macpan2","dir":"","previous_headings":"","what":"Fast and Flexible Compartmental Modelling","title":"Fast and Flexible Compartmental Modelling","text":"McMasterPandemic developed provide forecasts insights Canadian public health agencies throughout COVID-19 pandemic. Much learned developing general purpose compartmental modelling software experience, pressure deliver regular forecasts made difficult focus software . goal macpan2 project re-imagine McMasterPandemic, building ground architectural technological decisions address many lessons learned COVID-19 software. Impactful applied public health modelling requires many interdisciplinary steps along path epidemiological research teams operational decision makers. Researchers must quickly tailor model emerging public-health concern, validate calibrate data, work decision makers define model outputs useful stakeholders, configure models generate outputs, package insights appropriate format stakeholders. Unlike traditional modelling approaches, macpan2 tackles challenge software-engineering perspective, allows us systematically address bottlenecks along path impact ways make future solutions easier achieve. goal enable researchers focus core strengths fill knowledge gaps efficiently effectively. Although macpan2 designed compartmental modelling tool agnostic underlying computational engine, currently uses template model builder sole engine. Template model builder (TMB) R modelling package based C++ framework incorporating mature automatic differentiation matrix algebra libraries. Public Health Risk Sciences Division Public Health Agency Canada uses macpan2 (example, ).","code":""},{"path":"https://canmod.github.io/macpan2/index.html","id":"documentation","dir":"","previous_headings":"","what":"Documentation","title":"Fast and Flexible Compartmental Modelling","text":"Package reference Quick-start guide TMB engine [specification document] Project history trajectory [slides]","code":""},{"path":"https://canmod.github.io/macpan2/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Fast and Flexible Compartmental Modelling","text":"standard recommended way install macpan2 following command. command install current version macpan2. projects production need keep track specific versions macpan2, snapshots reproducibility information can obtained . Please see article explanation manage reproducibility using r-universe. get latest development version macpan2, command fails reason, alternative command install following. command requires remotes package assumes R environment set compile C++ code contained packages. Many workflows macpan2 also make use following packages.","code":"repos = c('https://canmod.r-universe.dev', 'https://cloud.r-project.org') install.packages('macpan2', repos = repos) remotes::install_github(\"canmod/macpan2\") install.packages(c(\"dplyr\", \"ggplot2\", \"tidyr\", \"broom.mixed\"))"},{"path":"https://canmod.github.io/macpan2/index.html","id":"hello-world","dir":"","previous_headings":"","what":"Hello World","title":"Fast and Flexible Compartmental Modelling","text":"following code specifies SI model, simplest model epidemiological transmission. See article example models documentation. Simulating model requires choosing number time-steps run model outputs generate. Syntax simulating macpan2 models designed combine standard data prep plotting tools R, demonstrate following code.","code":"library(macpan2) si = mp_tmb_model_spec(     before = S ~ 1 - I   , during = mp_per_capita_flow(         from     = \"S\"         ## compartment from which individuals flow       , to       = \"I\"         ## compartment to which individuals flow       , rate     = \"beta * I\"  ## expression giving _per-capita_ flow rate       , abs_rate = \"infection\" ## name for _absolute_ flow rate = beta * I * S     )   , default = list(I = 0.01, beta = 0.2) ) print(si) ## --------------------- ## Default values: ## --------------------- ##  matrix row col value ##       I          0.01 ##    beta          0.20 ##  ## --------------------- ## Before the simulation loop (t = 0): ## --------------------- ## 1: S ~ 1 - I ##  ## --------------------- ## At every iteration of the simulation loop (t = 1 to T): ## --------------------- ## 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I\", abs_rate = \"infection\") library(ggplot2) library(dplyr) (si  |> mp_simulator(time_steps = 50, outputs = c(\"I\", \"infection\"))  |> mp_trajectory()  |> mutate(quantity = case_match(matrix     , \"I\" ~ \"Prevalance\"     , \"infection\" ~ \"Incidence\"   ))  |> ggplot()   + geom_line(aes(time, value))   + facet_wrap(~ quantity, scales = \"free\")  + theme_bw() )"},{"path":"https://canmod.github.io/macpan2/index.html","id":"product-management","dir":"","previous_headings":"","what":"Product Management","title":"Fast and Flexible Compartmental Modelling","text":"project board tracks details bugs, tasks, feature development.","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":null,"dir":"Reference","previous_headings":"","what":"Binary Operator — BinaryOperator","title":"Binary Operator — BinaryOperator","text":"Convert function represents elementwise binary operator one consistent C++ engine. function intended clarify macpan2 treats binary operators, little different base R. difference clarified vignette(\"elementwise_binary_operators\"), BinaryOperator primarily used resource vignette.","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Binary Operator — BinaryOperator","text":"","code":"BinaryOperator(operator)"},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Binary Operator — BinaryOperator","text":"operator binary operator. Valid binary operations following characteristics.  - functions.  - exactly two arguments.  - ... arguments","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Binary Operator — BinaryOperator","text":"binary operator consistent C++ engine.","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Binary Operator — BinaryOperator","text":"","code":"set.seed(1L) A = matrix(abs(rnorm(6)), 3, 2)  # 3 by 2 matrix x = matrix(abs(rnorm(3)))        # 3 by 1 matrix y = t(abs(rnorm(2)))             # 1 by 2 matrix times = BinaryOperator(`*`) pow = BinaryOperator(`^`) identical(times(A, x), times(x, A))  ## TRUE #> [1] TRUE identical(pow(A, y), pow(y, A))  ## FALSE #> [1] FALSE"},{"path":"https://canmod.github.io/macpan2/reference/LedgerDefinition.html","id":null,"dir":"Reference","previous_headings":"","what":"Ledgers — LedgerDefinition","title":"Ledgers — LedgerDefinition","text":"ledger table rows identify specific instances functional form used define mp_dynamic_model. Ledgers commonly created using mp_join function following example.","code":"age = mp_index(Age = c(\"young\", \"old\")) state = mp_cartesian(   mp_index(Epi = c(\"S\", \"I\", \"R\")),   age ) mp_join(   from = mp_subset(state, Epi = \"S\"),   to = mp_subset(state, Epi = \"I\"),   by = list(from.to = \"Age\") ) #>     from      to #>  S.young I.young #>    S.old   I.old"},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":null,"dir":"Reference","previous_headings":"","what":"Reader — Reader","title":"Reader — Reader","text":"Construct objects reading data.","code":""},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reader — Reader","text":"","code":"Reader(...)  CSVReader(...)  JSONReader(...)  TXTReader(...)  RReader(...)  NULLReader(...)"},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reader — Reader","text":"... Character vectors giving path components file read.","code":""},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Reader — Reader","text":"CSVReader(): Read CSV files. JSONReader(): Read JSON files. TXTReader(): Read TXT files. RReader(): Read R files. NULLReader(): Placeholder reader always returns NULL.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":null,"dir":"Reference","previous_headings":"","what":"String Data — StringData","title":"String Data — StringData","text":"Create objects representing names labels dynamical model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"String Data — StringData","text":"","code":"StringDataFromFrame(data)  StringDataFromDotted(labels, name)  # S3 method for class 'StringData' print(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"String Data — StringData","text":"data Data frame names given column names labels elements columns. labels Character vector (dot-separated) partition labels. name Character scalar (dot-separated) partition name. x StringData object ... used present S3 method consistency.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"methods-by-generic-","dir":"Reference","previous_headings":"","what":"Methods (by generic)","title":"String Data — StringData","text":"print(StringData): Print StringData object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"String Data — StringData","text":"StringDataFromFrame(): Construct object data frame without dots either names values. StringDataFromDotted(): Construct object character scalar (dot-separated) partition names character vector (dot-separated) partition labels.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"String Data — StringData","text":"","code":"vars = (mp_cartesian(       mp_index(Epi = c(\"S\", \"I\", \"R\"))     , mp_index(Age = c(\"young\", \"old\"))   )   |> as.data.frame()   |> StringDataFromFrame() ) vars #> String data object with the following $frame(): #>   Epi   Age #> 1   S young #> 2   I young #> 3   R young #> 4   S   old #> 5   I   old #> 6   R   old vars$dot() #> String data object with the following $frame(): #>   Epi.Age #> 1 S.young #> 2 I.young #> 3 R.young #> 4   S.old #> 5   I.old #> 6   R.old"},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":null,"dir":"Reference","previous_headings":"","what":"Transform — Transform","title":"Transform — Transform","text":"Transform","code":""},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Transform — Transform","text":"","code":"Transform(variable, default = NULL, trans_variable = variable)  Identity(variable, default = NULL, trans_variable = variable)  Log(variable, default = NULL, trans_variable = sprintf(\"log_%s\", variable))  Logit(   variable,   default = NULL,   trans_variable = sprintf(\"logit_%s\", variable) )"},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Transform — Transform","text":"variable Character string giving name variable model. default Default value untransformed variable. NULL (default) value taken initial value model containing transformation. trans_variable Character string use name transformed version variable.","code":""},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Transform — Transform","text":"Identity(): Identity transformation. Log(): Log transformation. Logit(): Logit transformation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":null,"dir":"Reference","previous_headings":"","what":"Comparison Functions — comparison","title":"Comparison Functions — comparison","text":"Comparison Functions","code":""},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Comparison Functions — comparison","text":"","code":"all_equal(x, y)  all_consistent(x, y)  not_all_equal(x, y)  all_not_equal(x, y)"},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Comparison Functions — comparison","text":"x character object y character object","code":""},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Comparison Functions — comparison","text":"all_equal(): true corresponding elements x y equal, shape, missing values? all_consistent(): true corresponding elements x y either equal least one blank string, shape, missing values? not_all_equal(): Complement all_equal. all_not_equal(): know yet. Currently unused; remove?","code":""},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":null,"dir":"Reference","previous_headings":"","what":"Distributions — distribution","title":"Distributions — distribution","text":"Distributions can used specify prior likelihood components model calibration. Uniform Distribution (Improper), appropriate prior components - mp_uniform Normal Distribution - mp_normal Log-Normal Distribution - mp_log_normal Logit-Normal Distribution - mp_logit_normal Poisson Distribution - mp_poisson Negative Binomial Distribution - mp_neg_bin","code":""},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Distributions — distribution","text":"","code":"mp_uniform(trans_distr_param = list())  mp_normal(   location = mp_distr_param_null(\"location\"),   sd,   trans_distr_param = list(location = mp_identity, sd = mp_log) )  mp_log_normal(   location = mp_distr_param_null(\"location\"),   sd,   trans_distr_param = list(location = mp_identity, sd = mp_identity) )  mp_logit_normal(   location = mp_distr_param_null(\"location\"),   sd,   trans_distr_param = list(location = mp_identity, sd = mp_identity) )  mp_poisson(   location = mp_distr_param_null(\"location\"),   trans_distr_param = list(location = mp_identity) )  mp_neg_bin(   location = mp_distr_param_null(\"location\"),   disp,   trans_distr_param = list(location = mp_identity, disp = mp_log) )"},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Distributions — distribution","text":"trans_distr_param Named list transformations distributional parameter. See transform_distr_param list available transformations. location Location parameter. Specifying location parameter necessary distribution used prior distribution. used likelihood component location parameter taken simulated variable fitted data, location parameter left default. sd Standard deviation parameter. disp Dispersion parameter.","code":""},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Distributions — distribution","text":"distributional parameter arguments can specified either numeric value, character string giving parameter name, distributional parameter object (See fit_distr_params).","code":""},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":null,"dir":"Reference","previous_headings":"","what":"Empty Matrix — empty_matrix","title":"Empty Matrix — empty_matrix","text":"Empty matrices useful defining matrices need initialized get computed required expressions. can also provide useful placeholder matrices value certain phase simulation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Empty Matrix — empty_matrix","text":"","code":"empty_matrix"},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Empty Matrix — empty_matrix","text":"numeric matrix zero rows zero columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Empty Matrix — empty_matrix","text":"","code":"spec = mp_tmb_model_spec(during = list(x ~ time_step(0))) identical(spec$empty_matrices()$x, empty_matrix) ## TRUE #> [1] TRUE"},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":null,"dir":"Reference","previous_headings":"","what":"Engine Evaluation — engine_eval","title":"Engine Evaluation — engine_eval","text":"Evaluate expression TMB-based C++ simulation objective function engine. function useful trying engine_functions can used define macpan2 models.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Engine Evaluation — engine_eval","text":"","code":"engine_eval(   .expr,   ...,   .matrix_to_return,   .tmb_cpp = getOption(\"macpan2_dll\"),   .structure_labels = NullLabels() )"},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Evaluation — engine_eval","text":".expr Expression one-sided formula, right-hand-side treated expression evaluated. ... Named objects can coerced numeric matrices. .matrix_to_return Optional name one matrices given ... returned. argument missing, matrix returned matrix returned expression right-hand-side formula. .tmb_cpp Name C++ program defining engine. Typically just want use default, macpan2, unless extending engine . .structure_labels Deprecated.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Engine Evaluation — engine_eval","text":"Matrix produced right-hand-side matrix given .matrix_to_return provided.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Evaluation — engine_eval","text":"","code":"engine_eval(~ exp(y), y = pi) # ~ 23.14069 #>          [,1] #> [1,] 23.14069  # It is not currently possible to assign values to a subset of # a matrix in a natural way (e.g. you cannot do things like x[1] = exp(y)), # but you can achieve this functionality using the assign function. engine_eval(~ assign(x, 1, 0, exp(y))   , x = rep(0, 2)   , y = pi   , .matrix_to_return = \"x\" ) #>          [,1] #> [1,]  0.00000 #> [2,] 23.14069"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":null,"dir":"Reference","previous_headings":"","what":"Engine Functions — engine_functions","title":"Engine Functions — engine_functions","text":"Functions currently supported C++ TMB engine constructing expressions defining model simulations.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"quickest way experiment functions use engine_eval function, following example calculates force infection.   produce simulation using engine functions, one may use simple_sims.","code":"engine_eval(~ beta * I / N   , beta = 0.25   , I = 1e3   , N = 1e7 ) simple_sims(   iteration_exprs = list(x ~ x - 0.9 * x),   time_steps = 5,   mats = list(x = 1) )"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"elementwise-binary-operators","dir":"Reference","previous_headings":"","what":"Elementwise Binary Operators","title":"Engine Functions — engine_functions","text":"Elementwise binary operators take two matrix-valued arguments apply binary operator (e.g. +, *) set corresponding elements, return corresponding matrix-valued output containing resulting elements. 'corresponding' mean? two matrix-valued arguments shape (number rows columns), two elements correspond occur row column position two matrices. two matrices shape one row /one column either matrix, singleton rows columns recycled sufficiently many times match shape matrix. recycling singleton rows columns matrices still different shape, error thrown matrices said incompatible.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"x + y x - y x * y x / y x ^ y","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix dimensions compatible y. y – matrix dimensions compatible x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix binary operator applied elementwise necessary recycling rows /columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ 1 + 2) engine_eval(~ y * z, y = 1:3, z = matrix(1:6, 3, 2)) engine_eval(~ 1 / (1 - y), y = 1/4)"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-1","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"log(x) – Natural logarithm exp(x) – Exponential function cos(x) – Cosine function proportions(x, limit, eps) – matrix x / sum(x) rep(limit, length(x)) sum(x) < eps","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-1","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix limit – numeric value return elementwise proportions sum(x) < eps eps – numeric tolerance sum(x)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-1","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix dimensions x, unary function applied elementwise.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-1","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ log(y), y = c(2, 0.5))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-2","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":":– Inclusive ordered sequence integers two bounds. seq(, length, ) – Ordered sequence integers equal spacing adjacent values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-2","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"– Scalar integer giving first integer sequence. – Scalar integer giving last integer sequence. length – Number integers sequence. – Scalar giving difference adjacent values sequence.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-2","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"Column vector sequence integers.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-1","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"colon operator works much like base R version :. takes two scalar-valued integers returns column vector integers two inputs. seq function little different base R default, seq, allows user precise control length output length argument. base R function gives user option, default.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-2","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"Replicate Elements","code":"engine_eval(~ 1:10) engine_eval(~ seq(1, 10, 2))"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-3","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"rep(x, times) – Replicate column vector number times, repeatedly stacking top . rep_each – yet developed. rep_length – yet developed.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-3","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – scalar-valued variable repeat. times – scalar-valued integer variable giving number times repeat x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-3","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"Column vector times copies x stacked top .","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-3","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ rep(1, 10))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-4","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"x %*% y – Standard matrix multiplication. x %x% y – Kronecker product","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-4","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix. standard product, x must many columns y rows. y – matrix. standard product, y must many rows x columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-4","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix product x y.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-4","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ (1:10) %*% t(1:10)) engine_eval(~ (1:10) %x% t(1:10))"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"parenthesis","dir":"Reference","previous_headings":"","what":"Parenthesis","title":"Engine Functions — engine_functions","text":"order operations can enforced usual way round parentheses, (.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-5","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"c(...) – Stack columns arguments single column vector. cbind(...) – Create matrix containing columns group matrices number rows. rbind(...) – Create matrix containing rows group matrices number columns. matrix(x, rows, cols) – Reshape matrix rows rows cols columns. input x must rows * cols elements. t(x) – Standard matrix transpose.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-5","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"... – number dimensionally consistent matrices. definition dimensionally consistent depends function. x – Can matrix t, matrix must rows * cols elements. rows – Scalar integer giving number rows output. cols – Scalar integer giving number columns output.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-5","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"combined reshaped matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-2","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"number column vectors can combined bigger column vector. Column row vectors length can combined using cbind rbind functions respectively matrix function can used redefine numbers rows columns use arranging values matrix. works similarly base R matrix function takes arguments. hand, function differs substantially base R version must filled column byrow option. Matrices can transposed usual function, t.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-5","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ c(a, b, c), a = 1, b = 10:13, c = matrix(20:25, 3, 2)) engine_eval(~ cbind(a, 10 + a), a = 0:3) engine_eval(~ rbind(a, 10 + a), a = t(0:3)) engine_eval(~ matrix(1:12, 4, 3)) engine_eval(~ t(1:3))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-6","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"to_diag(x) – Create diagonal matrix setting diagonal column vector, x. from_diag(x) – Extract diagonal matrix, x, return diagonal column vector.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-6","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix (from_diag) column vector (to_diag). common assume x square from_diag required.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-6","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"to_diag(x) – Diagonal matrix x diagonal. from_diag(x) – Column vector containing diagonal x. value considered diagonal row index equal column index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-3","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"to_diag function can used produce diagonal matrix setting column vector equal desired diagonal. from_diag (almost) opposite, get column vector containing diagonal existing matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-6","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~from_diag(matrix(1:9, 3, 3))) engine_eval(~to_diag(from_diag(matrix(1:9, 3, 3)))) engine_eval(~from_diag(to_diag(from_diag(matrix(1:9, 3, 3)))))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-7","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"sum(...) – Sum elements matrices passed .... col_sums(x) – Row vector containing sums column. row_sums(x) – Column vector containing sums row. group_sums(x, f, n) – Column vector containing sums groups elements x. groups determined integers f order sums output determined integers.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-7","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"... – number matrices shape. x – matrix dimensions, except group_sums expects x column vector. f – column vector length x containing integers 0 m-1, given m unique groups. Elements f refer indices x grouped summed. n – column vector length m. f contain group k [0, m-1], group_sums skips group output index k+1 n[k+1].","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-7","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix containing sums subsets inputs.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-4","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"row_sums col_sums similar base R rowSums colSums functions, slightly different behaviour. particular, row_sums function returns column vector col_sums function returns row vector. specific shape required transpose t function must explicitly used.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-7","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"x = 1 y = 1:3 A = matrix(1:12, 4, 3) engine_eval(~ sum(y), y = y) engine_eval(~ sum(x, y, A), x = x, y = y, A = A) engine_eval(~ col_sums(A), A = A) engine_eval(~ row_sums(A), A = A) engine_eval(~ group_sums(x, f, n), x = 1:10, f = rep(0:3, 1:4), n = c(1:4))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-8","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"x[,j] – Matrix containing subset rows columns x. block(x,,j,n,m) – Matrix containing contiguous subset rows columns x https://eigen.tuxfamily.org/dox/group__TutorialBlockOperations.html","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-8","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix. – integer column vector ([) integer scalar (block) containing indices rows extract ([) index first row extract (block). j – integer column vector ([) integer scalar (block) containing indices columns extract ([) index first column extract (block). n – Number rows block return. m – Number columns block return.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-8","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix containing subset rows columns x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-5","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"Note zero-based indexing used first row/column gets index, 0, etc.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-8","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ A[c(3, 1, 2), 2], A = matrix(1:12, 4, 3)) engine_eval(~ block(x,i,j,n,m), x = matrix(1:12, 4, 3), i=1, j=1, n=2, m=2)"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"accessing-past-values-in-the-simulation-history","dir":"Reference","previous_headings":"","what":"Accessing Past Values in the Simulation History","title":"Engine Functions — engine_functions","text":"matrices simulation history saved, possible bind rows columns past versions matrices single matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-9","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"rbind_lag(x, lag, t_min) – Bind rows versions x recorded end simulation iterations corresponding time lags given integers lag. rbind_time(x, t, t_min) – Bind rows versions x recorded end simulation iterations corresponding integers t. cbind_lag(x, lag, t_min) – Bind columns versions x recorded end simulation iterations corresponding time lags given integers lag. (TODO – cbind_lag developed yet) cbind_time(x, t, t_min) – Bind columns versions x recorded end simulation iterations corresponding integers t. (TODO – cbind_lag developed yet)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-9","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix saved history number columns (rbind_*) rows (cbind_*) change throughout simulation. lag – Integer vector giving numbers time steps current step obtain past values x. t – Integer vector giving time steps obtain past values x. t_min – Integer giving minimum time step allowed accessed. time-steps t implied lag t_min ignored.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-9","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix containing values x past times.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"time-indexing","dir":"Reference","previous_headings":"","what":"Time Indexing","title":"Engine Functions — engine_functions","text":"Get update index current lagged time step index current time group. time group contiguous set time steps defined two change points.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-10","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"time_step(lag): Get time-step associated particular lag current time-step. lagged time-step less zero, function returns zero. time_group(index, change_points): Update index associated current time group. current group defined minimum elements change_points greater current time step. time group index index associated element. Please see examples , easier understand explanation. time_var(x, change_points): improvement time_group. Returns values x time steps change_points, return value remains constant change_points.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-10","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x: Column vector representing time series. time_var return value x corresponding element change_points contains current time. lag: Number time-steps look back time-step return. change_points: Increasing column vector time steps giving lower bound time group.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-10","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"1--1 matrix time-step lag steps ago, zero t+1 < lag","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-9","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"simple_sims(   iteration_exprs = list(x ~ time_step(0)),   time_steps = 10,   mats = list(x = empty_matrix) ) sims = simple_sims(   iteration_exprs = list(     j ~ time_group(j, change_points),     time_varying_parameter ~ time_variation_schedule[j]   ),   mats = list(     j = 0,     change_points = c(0, 4, 7),     time_variation_schedule = c(42, pi, sqrt(2)),     time_varying_parameter = empty_matrix   ),   time_steps = 10, ) set.seed(1L) change_points = c(0,2,5) x_val = rnorm(length(change_points)) simple_sims(     iteration_exprs = list(x ~ time_var(x_val,change_points))   , int_vecs = list(change_points = change_points)   , mats = list(x = empty_matrix, x_val=x_val)   , time_steps = 10 )"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"convolution","dir":"Reference","previous_headings":"","what":"Convolution","title":"Engine Functions — engine_functions","text":"One may take convolution element matrix, x, simulation time using kernel, k. two arguments function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-11","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"convolution(x, k)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-11","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix containing elements convolved. k – column vector giving convolution kernel.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-11","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix size x convolutions, \\(y_{ij}\\), element, \\(x_{ij}\\), given following. $$y_{ij} = \\sum_{\\tau = 0} x_{ij}(t-\\tau) k(\\tau)$$ unless \\(t < \\tau\\), case, $$y_{ij} = $$ \\(y_{ij}\\) convolution, \\(x_{ij}(t)\\) value \\(x_{ij}\\) time step, \\(t\\), \\(k(\\tau)\\) value kernel lag, \\(\\tau\\), \\(\\lambda\\) length kernel.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-6","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"empty matrices encountered looking back time, treated matrices zeros. Similarly, matrices encounte x","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"clamp","dir":"Reference","previous_headings":"","what":"Clamp","title":"Engine Functions — engine_functions","text":"Smoothly clamp elements matrix get closer 0 tolerance, eps, default 1e-12. output clamp function follows.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-12","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"clamp(x, eps)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-12","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x : matrix elements remain positive. eps : small positive number giving theoretical minimum elements returned matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"probability-densities","dir":"Reference","previous_headings":"","what":"Probability Densities","title":"Engine Functions — engine_functions","text":"probability densities first two arguments. observed simulated simulated argument gives matrix means observed values densities evaluated. Additional arguments distributional parameters standard deviation dispersion parameter. densities given log-densities, like density must pass result exp function. simulated matrix additional parameter matrices either single row single column, singleton rows columns repeated match number rows columns observed matrix. feature allows one things like specify single common mean several values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-13","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"dpois(observed, simulated) – Log Poisson density based dpois TMB function. dnbinom(observed, simulated, over_dispersion) – Log negative binomial density based dnbinom TMB function. get variance function requires use expression, simulated + simulated^2/over_dispersion, following p.165 book dnorm(observed, simulated, standard_deviation) – Log normal density based dnorm TMB function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-13","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"observed – Matrix observed values density evaluated. simulated – Matrix distributional means, singleton rows columns recycled match numbers rows columns observed. over_dispersion – -dispersion parameter given (simulated/standard_deviation)^2 - simulated). standard_deviation – Standard deviation parameter.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"pseudo-random-number-generators","dir":"Reference","previous_headings":"","what":"Pseudo-Random Number Generators","title":"Engine Functions — engine_functions","text":"random number generator functions mean first argument. Subsequent arguments give additional distributional parameters. Singleton rows columns matrices passed additional distributional parameters recycled arguments number rows columns. functions return matrix shape mean pseudo-random numbers deviating mean mean matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-14","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"rpois(mean) – Pseudo-random Poisson distributed values. rnbinom(mean, over_dispersion) – Pseudo-random negative binomially distributed values. rnorm(mean, standard_deviation) – Pseudo-random normal values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-14","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"mean – Matrix means simulate pseudo-random variation. over_dispersion – Matrix -dispersion parameters given (simulated/standard_deviation)^2 - simulated). standard_deviation – Matrix standard deviation parameters.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"assign","dir":"Reference","previous_headings":"","what":"Assign","title":"Engine Functions — engine_functions","text":"Assign values subset elements matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-15","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"assign(x, , j, v)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-15","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – Matrix elements updated values v. – Column vector row indices pointing elements x updated. indices paired v. length equal v, must single index gets paired every element v. Indices zero-based, =0 corresponds first row. j – Column vector column indices pointing elements x updated. indices paired v. length j equal v, must single index gets paired every element v. Indices zero-based, j=0 corresponds first column. v – Column vector values replace elements x locations given j.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-12","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"assign function called return value, empty_matrix, rather modify x replacing components v.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-10","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"x = matrix(1:12, 3, 4) engine_eval(~ x + 1, x = x) engine_eval(~ x + 1, x = x, .matrix_to_return = \"x\") engine_eval(~ assign(x, 2, 1, 100), x = x, .matrix_to_return = \"x\") engine_eval(~ assign(x   , c(2, 1, 0)   , 0   , c(100, 1000, 10000) ), x = x, .matrix_to_return = \"x\")"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"unpack","dir":"Reference","previous_headings":"","what":"Unpack","title":"Engine Functions — engine_functions","text":"Unpack elements matrix smaller matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-16","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"unpack(x, ...)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-16","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – Matrix elements distributed matrices passed .... ... – Matrices elements replaced values elements x column-major order. matrices must named matrices computed fly using expressions. Note even subsetting (e.g. unpack(x, y[0], y[3])) counts expression. use-case require assign function assign(y, c(0, 3), 0, x).","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-13","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"unpack function called return value, empty_matrix, rather modify matrices ... replacing least components x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-11","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"fill matrix integers 1 12 unpack one---time two column vectors, x y. returning y see integers first three used x.","code":"engine_eval(~unpack(matrix(1:12, 3, 4), x, y)   , x = rep(0, 3)   , y = rep(1, 5)   , .matrix_to_return = \"y\" )"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"print-matrix","dir":"Reference","previous_headings":"","what":"Print Matrix","title":"Engine Functions — engine_functions","text":"Print value matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-17","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"print(x)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-17","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – Name matrix model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-14","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"empty_matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-12","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"simple_sims(      list(dummy ~ print(x), x ~ x / 2)    , time_steps = 10    , mats = list(x = 2) )"},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":null,"dir":"Reference","previous_headings":"","what":"Finalizers — finalizer","title":"Finalizers — finalizer","text":"Finalizers","code":""},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Finalizers — finalizer","text":"","code":"finalizer_char(x)  finalizer_index(x)"},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Finalizers — finalizer","text":"x Raw parsed expression.","code":""},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Finalizers — finalizer","text":"finalizer_char(): Finalize parsed expression parse table little human readable. finalizer_index(): Finalize parsed expression parse table can passed C++ engine.","code":""},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":null,"dir":"Reference","previous_headings":"","what":"Find all Paths — find_all_paths","title":"Find all Paths — find_all_paths","text":"Find paths compartmental model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Find all Paths — find_all_paths","text":"","code":"find_all_paths(edges_df, start_node_guesses = character(0L))"},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Find all Paths — find_all_paths","text":"edges_df data frame column. start_node_guesses Optional guesses nodes start paths. useful models directed acyclic graphs (DAGs).","code":""},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Find all Paths — find_all_paths","text":"List character vectors state variable names, vector describing path model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":null,"dir":"Reference","previous_headings":"","what":"Fitting Distributional Parameters — fit_distr_params","title":"Fitting Distributional Parameters — fit_distr_params","text":"Distributional parameters can added list parameters fit calibration. default, distributional parameters priors likelihoods fit. Use mp_nofit exclude distributional parameters fit mp_fit fit .","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fitting Distributional Parameters — fit_distr_params","text":"","code":"mp_fit(x, trans = DistrParamTransDefault())  mp_nofit(x, trans = DistrParamTransDefault())"},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fitting Distributional Parameters — fit_distr_params","text":"x numeric starting value distributional parameter fit, character name existing variable model default starting value use. trans transformation apply distributional parameter. default, distributional parameters inherit default transformation associated distribution. example, standard deviation parameter sd mp_normal distributions default log transformation specified using mp_log.","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Fitting Distributional Parameters — fit_distr_params","text":"distributional parameter object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Fitting Distributional Parameters — fit_distr_params","text":"","code":"# First we call the SIR model spec, and generate some data for calibration. spec = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") data = mp_simulator(spec, 50, \"infection\") |> mp_trajectory()  # Suppose we want to specify a Normal prior on the transmission parameter  # beta, and we are interested in estimating the prior standard deviation. # Here we use `mp_fit` to estimate the standard deviation, `sd`, and we  # provide a numeric starting value for `sd` in the optimization.  cal = mp_tmb_calibrator(     spec   , data   , traj = \"infection\"   , par = list(beta = mp_normal(location = 0.35, sd = mp_fit(0.1)))   , default = list(beta = 0.25) )  # When viewing the calibration objective function we can see the additional # prior density term added for beta. The standard deviation parameter has # been automatically named 'distr_params_log_sd_beta'. cal$simulator$tmb_model$obj_fn$obj_fn_expr #> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta,  #>     0.35, exp(distr_params_log_sd_beta))) #> <environment: 0x55f2f1578958>  # Next we optimize and view the fitted parameters. We can see the  # distributional parameter in the coefficient table with a default value  # equal to the numeric value we provided to `mp_fit` above. mp_optimize(cal) #> outer mgc:  379.7835  #> outer mgc:  253.0639  #> outer mgc:  40.08291  #> outer mgc:  1.60249  #> outer mgc:  0.002833777  #> outer mgc:  8.986787e-09  #> $par #>     params     params  #>  0.2005665 -1.9009040  #>  #> $objective #> [1] 49.2679 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 5 #>  #> $evaluations #> function gradient  #>        6        6  #>  #> $message #> [1] \"relative convergence (4)\" #>  mp_tmb_coef(cal) #> outer mgc:  8.986787e-09  #> outer mgc:  11.62005  #> outer mgc:  11.92421  #> outer mgc:  0.0133705  #> outer mgc:  0.01339728  #> outer mgc:  31.09242  #>       term                  mat row col default  type  estimate   std.error #> 1   params                 beta   0   0    0.25 fixed 0.2005665 0.009251899 #> 2 params.1 distr_params_sd_beta   0   0    0.10 fixed 0.1494335 0.106069656  # If instead we want control over the name of the new fitted distributional # parameter, we can add a new variable to our model specification with the  # default value set to the desired optimization starting value. updated_spec = spec |> mp_tmb_insert(default = list(sd_var = 0.1))  # In the calibrator, we use the name of this newly added variable, \"sd_var\", # as input to `mp_fit`. cal = mp_tmb_calibrator(     updated_spec   , data   , traj = \"infection\"   , par = list(beta = mp_normal(location = 0.35, sd = mp_fit(\"sd_var\")))   , default = list(beta = 0.25) )  # We can see this distributional parameter get propogated to the objective  # function and the fitted parameter table. cal$simulator$tmb_model$obj_fn$obj_fn_expr #> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta,  #>     0.35, exp(sd_var))) #> <environment: 0x55f2f0b13b60> mp_optimize(cal) #> outer mgc:  389.7016  #> outer mgc:  258.9379  #> outer mgc:  42.94112  #> outer mgc:  2.418362  #> outer mgc:  0.01416442  #> outer mgc:  7.421077e-06  #> outer mgc:  3.974682e-12  #> $par #>     params     params  #>  0.2005665 -1.9009040  #>  #> $objective #> [1] 49.2679 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 6 #>  #> $evaluations #> function gradient  #>        7        7  #>  #> $message #> [1] \"relative convergence (4)\" #>  mp_tmb_coef(cal) #> outer mgc:  3.974682e-12  #> outer mgc:  11.62005  #> outer mgc:  11.92421  #> outer mgc:  0.01337051  #> outer mgc:  0.01339727  #> outer mgc:  31.09242  #>       term    mat row col default  type   estimate   std.error #> 1   params   beta   0   0    0.25 fixed  0.2005665 0.009251899 #> 2 params.1 sd_var   0   0    0.10 fixed -1.9009040 0.709811879"},{"path":"https://canmod.github.io/macpan2/reference/initial_valid_vars.html","id":null,"dir":"Reference","previous_headings":"","what":"Initial Valid Variables — initial_valid_vars","title":"Initial Valid Variables — initial_valid_vars","text":"Initial Valid Variables","code":""},{"path":"https://canmod.github.io/macpan2/reference/initial_valid_vars.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Initial Valid Variables — initial_valid_vars","text":"","code":"initial_valid_vars(valid_var_names)"},{"path":"https://canmod.github.io/macpan2/reference/initial_valid_vars.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Initial Valid Variables — initial_valid_vars","text":"valid_var_names Character vector variable names.","code":""},{"path":"https://canmod.github.io/macpan2/reference/macpan2-package.html","id":null,"dir":"Reference","previous_headings":"","what":"macpan2 — macpan2-package","title":"macpan2 — macpan2-package","text":"R package -McMasterPandemic package compartmental epidemic modelling forecasting analysis infectious diseases.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/macpan2-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"macpan2 — macpan2-package","text":"Maintainer: Steve Walker swalk@mcmaster.ca Authors: Weiguang Guan Jen Freeman Ben Bolker Darren Flynn-Primrose contributors: Irena Papst [contributor] Michael Li [contributor]","code":""},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate an Arithmetic Expression Parser — make_expr_parser","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"Generate Arithmetic Expression Parser","code":""},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"","code":"make_expr_parser(parser_name = NULL, finalizer = force)"},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"parser_name Name parsing function character string. longer used, still present back-compatibility. finalizer Function used post-process parsed formula. default identity finalizer, returns parsed formula .  good choices finalizer_char, can used understand formula parsed, finalizer_index, can passed C++ engine. result function another function takes single argument, x.  resulting function recursive.  x argument one-sided formula first time recursive function called.  subsequent evaluations recursion, x list following structure.  x formula, must contain named list functions called valid_funcs named list variables called valid_vars. x list names numeric objects represent leaf parse tree n integer vector length x give number arguments associated functions x 0 otherwise index identifying element x corresponding first argument associated function 0 function valid_funcs named list valid functions extracted environment formula parsed valid_vars named list default values valid variables extracted environment formula parsed input_expr_as_string input formula stored string","code":""},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"","code":"parser = make_expr_parser(finalizer = finalizer_char) foi = ~ beta * I / 100 valid_funcs = setNames(   list(`*`, `/`),   c(\"*\", \"/\") ) valid_vars = list(beta = 0.1, I = 30) parser(foi) #>      x n i #> 1    ~ 1 1 #> 2    / 2 2 #> 3    * 2 4 #> 4  100 0 0 #> 5 beta 0 0 #> 6    I 0 0"},{"path":"https://canmod.github.io/macpan2/reference/mp_aggregate.html","id":null,"dir":"Reference","previous_headings":"","what":"Aggregate an Index — mp_aggregate","title":"Aggregate an Index — mp_aggregate","text":"Create one-column ledger (see LedgerDefinition) rows identifying instances aggregation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_aggregate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Aggregate an Index — mp_aggregate","text":"","code":"mp_aggregate(index, by = \"Group\", ledger_column = \"group\")"},{"path":"https://canmod.github.io/macpan2/reference/mp_aggregate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Aggregate an Index — mp_aggregate","text":"index index aggregate . column set label group . default dummy constant \"Group\" column created. ledger_column Name column output ledger describes groups.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":null,"dir":"Reference","previous_headings":"","what":"Cartesian Product of Index Tables — mp_cartesian","title":"Cartesian Product of Index Tables — mp_cartesian","text":"Produce new index table taking possible pairwise combinations input tables. useful producing product models expand model components stratification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cartesian Product of Index Tables — mp_cartesian","text":"","code":"mp_cartesian(...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cartesian Product of Index Tables — mp_cartesian","text":"... Index tables (see mp_index).","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Cartesian Product of Index Tables — mp_cartesian","text":"","code":"mp_cartesian(   mp_index(Epi = c(\"S\", \"I\")),   mp_index(Age = c(\"young\", \"old\")) ) #>  Epi   Age #>    S young #>    I young #>    S   old #>    I   old  si = mp_index(Epi = c(\"S\", \"I\")) age = mp_index(Age = c(\"young\", \"old\")) loc = mp_index(City = c(\"hamilton\", \"toronto\")) vax = mp_index(Vax = c(\"unvax\", \"vax\")) (si   |> mp_cartesian(age)   |> mp_cartesian(loc)   |> mp_cartesian(vax) ) #>  Epi   Age     City   Vax #>    S young hamilton unvax #>    I young hamilton unvax #>    S   old hamilton unvax #>    I   old hamilton unvax #>    S young  toronto unvax #>    I young  toronto unvax #>    S   old  toronto unvax #>    I   old  toronto unvax #>    S young hamilton   vax #>    I young hamilton   vax #>    S   old hamilton   vax #>    I   old hamilton   vax #>    S young  toronto   vax #>    I young  toronto   vax #>    S   old  toronto   vax #>    I   old  toronto   vax  flow_rates = mp_index(Epi = c(\"infection\", \"recovery\")) mp_union(   mp_cartesian(     mp_subset(flow_rates, Epi = \"infection\"),     age   ),   mp_subset(flow_rates, Epi = \"recovery\") ) #>        Epi   Age #>  infection young #>  infection   old #>   recovery"},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":null,"dir":"Reference","previous_headings":"","what":"Default Values — mp_default","title":"Default Values — mp_default","text":"Default Values","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Default Values — mp_default","text":"","code":"mp_default(model)  mp_default_list(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Default Values — mp_default","text":"model model object extract default values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Default Values — mp_default","text":"long-format data frame default values matrices required input model objects. columns output matrix, row, col, value. Scalar matrices entries row col columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Default Values — mp_default","text":"mp_default_list(): List default variables matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_model.html","id":null,"dir":"Reference","previous_headings":"","what":"Dynamic Model — mp_dynamic_model","title":"Dynamic Model — mp_dynamic_model","text":"'old' model specification function tested workshop. Currently still drives engine-agnostic-grammar vignette, plan replace function mp_tmb_model_spec model specification functions.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_model.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Dynamic Model — mp_dynamic_model","text":"","code":"mp_dynamic_model(   expr_list = ExprList(),   ledgers = list(),   init_vecs = list(),   unstruc_mats = list() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_model.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Dynamic Model — mp_dynamic_model","text":"expr_list Expression list. ledgers Ledgers. init_vecs Initial structured vectors. unstruc_mats Initial unstructured matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_simulator.html","id":null,"dir":"Reference","previous_headings":"","what":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","title":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","text":"'old' function tested workshop. Currently still drives engine-agnostic-grammar vignette, plan replace function mp_simulator.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_simulator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","text":"","code":"mp_dynamic_simulator(   dynamic_model,   time_steps = 0L,   vectors = NULL,   unstruc_mats = NULL,   mats_to_save = NULL,   mats_to_return = NULL,   params = OptParamsList(0),   random = OptParamsList(),   obj_fn = ObjectiveFunction(~0),   log_file = LogFile(),   do_pred_sdreport = TRUE,   tmb_cpp = \"macpan2\",   initialize_ad_fun = TRUE,   ... )"},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_simulator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","text":"dynamic_model Object product mp_dynamic_model. time_steps Number time steps simulate. vectors Named list named vectors initial values simulations referenced expression list dynamic model. unstruc_mats = Named list objects can coerced numerical matrices used expression list dynamic model. mats_to_save TODO mats_to_return TODO params TODO random TODO obj_fn TODO log_file TODO do_pred_sdreport TODO tmb_cpp TODO initialize_ad_fun TODO ... TODO","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":null,"dir":"Reference","previous_headings":"","what":"Describe Statistical Effects — mp_effects_descr","title":"Describe Statistical Effects — mp_effects_descr","text":"Additional information can joined output tidy.TMB tidy.stanfit functions broom.mixed package.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Describe Statistical Effects — mp_effects_descr","text":"","code":"mp_effects_descr(model)  mp_add_effects_descr(coef_table, model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Describe Statistical Effects — mp_effects_descr","text":"model model TMB engine can used compute tables statistical effects. coef_table Coefficient table probably generated using mp_tmb_coef mp_tmbstan_coef, also perhaps generated directly using tidy.TMB tidy.stanfit methods broom.mixed package.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Describe Statistical Effects — mp_effects_descr","text":"mp_add_effects_descr(): Convenience function adding coefficient descriptions calibrated model coef_tables generated mp_tmb_coef mp_tmbstan_coef.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":null,"dir":"Reference","previous_headings":"","what":"State Updates — mp_euler","title":"State Updates — mp_euler","text":"Use functions update model spec state variables updated according different numerical methods.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"State Updates — mp_euler","text":"","code":"mp_euler(model)  mp_rk4(model)  mp_euler_multinomial(model)  mp_hazard(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"State Updates — mp_euler","text":"model Object quantities explicitly marked state variables.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"State Updates — mp_euler","text":"default update method model specifications produced using mp_tmb_model_spec mp_euler. update method yields difference-equation model state updated per time-step using absolute flow rate difference steps. state update functions used modify model specification use particular kind state update. see modified models particular example one may use mp_expand function (see examples).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"State Updates — mp_euler","text":"mp_rk4(): ODE solver using Runge-Kutta 4. formulas appear model flows list updated RK4 contain functions getOption(\"macpan2_non_iterable_funcs\") make state variable assignments (.e., left-hand-side contain state variables). formula meet conditions evaluated time-step three RK4 iterations taken. default, time_var function functions generate random numbers (e.g., rbinom) iterable. Functions generate random numbers called state update methods repeat expressions per time-step (e.g., mp_euler), repeating functions RK4 make difficult compare methods. really want regenerate random numbers RK4 iteration, can setting option appropriately. time_var function assumes called per time-step, never removed list non-iterable functions. Although principle make sense update state variables manually, currently causes us confused. therefore require state variables updates set explicitly (e.g., mp_per_capita_flow) explicit. mp_euler_multinomial(): Update state process error given Euler-multinomial distribution. mp_hazard(): Update state hazard steps, equivalent taking step given expected value Euler-multinomial distribution.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"State Updates — mp_euler","text":"","code":"sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") sir #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #>  sir |> mp_euler()             |> mp_expand() #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ S * (I * beta/N) #> 2: recovery ~ I * (gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>  sir |> mp_rk4()               |> mp_expand() #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #>  1: infection ~ S * (I * beta/N) #>  2: recovery ~ I * (gamma) #>  3: k1_S ~ -infection #>  4: k1_I ~ +infection - recovery #>  5: k1_R ~ +recovery #>  6: infection ~ (S + (k1_S/2)) * ((I + (k1_I/2)) * beta/N) #>  7: recovery ~ (I + (k1_I/2)) * (gamma) #>  8: k2_S ~ -infection #>  9: k2_I ~ +infection - recovery #> 10: k2_R ~ +recovery #> 11: infection ~ (S + (k2_S/2)) * ((I + (k2_I/2)) * beta/N) #> 12: recovery ~ (I + (k2_I/2)) * (gamma) #> 13: k3_S ~ -infection #> 14: k3_I ~ +infection - recovery #> 15: k3_R ~ +recovery #> 16: infection ~ (S + k3_S) * ((I + k3_I) * beta/N) #> 17: recovery ~ (I + k3_I) * (gamma) #> 18: k4_S ~ -infection #> 19: k4_I ~ +infection - recovery #> 20: k4_R ~ +recovery #> 21: S ~ S + (k1_S + 2 * k2_S + 2 * k3_S + k4_S)/6 #> 22: I ~ I + (k1_I + 2 * k2_I + 2 * k3_I + k4_I)/6 #> 23: R ~ R + (k1_R + 2 * k2_R + 2 * k3_R + k4_R)/6 #>  sir |> mp_euler_multinomial() |> mp_expand() #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ reulermultinom(S, (I * beta/N)) #> 2: recovery ~ reulermultinom(I, gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":null,"dir":"Reference","previous_headings":"","what":"Expand Model — mp_expand","title":"Expand Model — mp_expand","text":"Expand structured model represented unstructured format requiring verbose description. Currently, applicable mp_tmb_model_spec objects explicit flows (e.g. mp_per_capita_flow). models, mp_expand produces model expression lists composed entirely plain R formulas.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Expand Model — mp_expand","text":"","code":"mp_expand(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Expand Model — mp_expand","text":"model model object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Expand Model — mp_expand","text":"","code":"sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") print(sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #>  print(mp_expand(sir)) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ S * (I * beta/N) #> 2: recovery ~ I * (gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_extract.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract Index — mp_extract","title":"Extract Index — mp_extract","text":"Extract index particular dimension ledger ledger object containing one ledgers.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_extract.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract Index — mp_extract","text":"","code":"mp_extract(x, dimension_name)"},{"path":"https://canmod.github.io/macpan2/reference/mp_extract.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract Index — mp_extract","text":"x Object dimension_name Name dimension used ledger.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_factors.html","id":null,"dir":"Reference","previous_headings":"","what":"Factor an Index — mp_factors","title":"Factor an Index — mp_factors","text":"Factor Index","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_factors.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Factor an Index — mp_factors","text":"","code":"mp_factors(index, unpack = c(\"no\", \"maybe\", \"yes\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_factors.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Factor an Index — mp_factors","text":"index index factored. unpack Place factors global environment?","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":null,"dir":"Reference","previous_headings":"","what":"Final Values — mp_final","title":"Final Values — mp_final","text":"Return values variables simulation loop finished final set expressions evaluated.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Final Values — mp_final","text":"","code":"mp_final(model)  mp_final_list(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Final Values — mp_final","text":"model Object can used simulate.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Final Values — mp_final","text":"mp_final_list(): Final values formatted list matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow Frame (experimental) — mp_flow_frame","title":"Flow Frame (experimental) — mp_flow_frame","text":"Get data frame representing flows model specification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow Frame (experimental) — mp_flow_frame","text":"","code":"mp_flow_frame(spec, topological_sort = TRUE, loops = \"^$\")"},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow Frame (experimental) — mp_flow_frame","text":"spec mp_tmb_model_spec. topological_sort states topologically sorted respect main direction flow? loops Pattern matching names flows make flow model DAG, critical assumption topologically sorting order states flows output. relevant topological_sort used.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Flow Frame (experimental) — mp_flow_frame","text":"data frame gives information provided calls mp_per_capita_flow mp_per_capita_inflow.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_group.html","id":null,"dir":"Reference","previous_headings":"","what":"Group an Index — mp_group","title":"Group an Index — mp_group","text":"Create new index fewer columns create names aggregated vector labelled input index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_group.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Group an Index — mp_group","text":"","code":"mp_group(index, by)"},{"path":"https://canmod.github.io/macpan2/reference/mp_group.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Group an Index — mp_group","text":"index Index group rows. Column set label group .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":null,"dir":"Reference","previous_headings":"","what":"Model Quantity Index Table — mp_index","title":"Model Quantity Index Table — mp_index","text":"Make index table enumerate model quantity labels category. objects generalize wrap data.frames, column label category row index. Indices must contain letters, numbers, underscores. Blank empty string entries allowed, missing values (NAs) .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model Quantity Index Table — mp_index","text":"","code":"mp_index(..., labelling_column_names)  # S3 method for class 'Index' print(x, ...)  # S3 method for class 'Index' names(x)  # S3 method for class 'Index' labelling_column_names(x)  # S3 method for class 'Index' labels(object, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model Quantity Index Table — mp_index","text":"... Character vectors combine produce index. Alternatively, number data frames character-valued columns. data frames supplied, rows bound result converted index possible. labelling_column_names character vector names index used label model components (.e. rows) described. labelling_column_names duplicates must contain least one name. index given labelling_column_names must uniquely identify row. default NULL gives set columns, order starting first column, required uniquely identify row. x index. object index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Model Quantity Index Table — mp_index","text":"example, following index table describes state variables model:   , column Epi denotes category labels epidemiological. nothing special specific choice category name; also used another name like Compartment. However, complicated models, good think carefully choosing descriptive category names. example, age-structured SIR model, add Age column generate index table follows:   , first column index table labeled Compartment somewhat misleading, compartments actually just \"S\", \"\", \"R\", epidemiological states stratified age groups \"young\" \"old\". index table also generated first specifying individual index tables Epi Age columns, using macpan2 product function combines tables single index table:   mp_cartesian() function produce table entries possible combinations individual index tables. \"See Also\" section mp_cartesian() help page catalogues available product functions. can produce full labels model quantities, simply dot-concatenated indices, one entry index table, using labels() function:   Dots allowed indices labels can inverted reproduce original index table (provided column names can retrieved). recommended use UpperCamelCase columns index tables single uppercase characters (\"S\", \"\"), lowercase character strings (\"gamma\"), /snake_case strings (\"aging_rate\") indices. convention helps reading code contains references column names indices.","code":"sir = mp_index(Epi = c(\"S\", \"I\", \"R\")) print(sir) #>  Epi #>    S #>    I #>    R sir_age = mp_index(  Epi = rep(c(\"S\", \"I\", \"R\"), 2),  Age = rep(c(\"young\", \"old\"), each = 3) ) print(sir_age) #>  Epi   Age #>    S young #>    I young #>    R young #>    S   old #>    I   old #>    R   old sir = mp_index(Epi = c(\"S\", \"I\", \"R\")) age = mp_index(Age = c(\"young\", \"old\")) prod = mp_cartesian(sir, age) prod #>  Epi   Age #>    S young #>    I young #>    R young #>    S   old #>    I   old #>    R   old #> [1] \"S.young\" \"I.young\" \"R.young\" \"S.old\"   \"I.old\"   \"R.old\""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Model Quantity Index Table — mp_index","text":"print(Index): Print index. names(Index): Get names columns index. labelling_column_names(Index): Retrieve labelling_column_names index. names columns used label model components. labels(Index): Convert index character vector giving labels associated model component (.e. row) described.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Model Quantity Index Table — mp_index","text":"","code":"state = mp_index(   Epi = c(\"S\", \"I\", \"S\", \"I\"),   Age = c(\"young\", \"young\", \"old\", \"old\") ) print(state) #>  Epi   Age #>    S young #>    I young #>    S   old #>    I   old labels(state) #> [1] \"S.young\" \"I.young\" \"S.old\"   \"I.old\"   mp_cartesian(state, mp_index(City = c(\"hamilton\", \"toronto\"))) #>  Epi   Age     City #>    S young hamilton #>    I young hamilton #>    S   old hamilton #>    I   old hamilton #>    S young  toronto #>    I young  toronto #>    S   old  toronto #>    I   old  toronto"},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":null,"dir":"Reference","previous_headings":"","what":"Initial Values — mp_initial","title":"Initial Values — mp_initial","text":"Return data frame containing values variables end phase, right simulation loop begins (.e. right phase).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Initial Values — mp_initial","text":"","code":"mp_initial(model)  mp_initial_list(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Initial Values — mp_initial","text":"model model specification object model simulator object extract initial values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Initial Values — mp_initial","text":"long-format data frame initial values matrices. columns output matrix, time, row, col, value. Scalar matrices entries row col columns. phase corresponds time value 0.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Initial Values — mp_initial","text":"mp_initial_list(): List initial variables matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":null,"dir":"Reference","previous_headings":"","what":"Join Indexes — mp_join","title":"Join Indexes — mp_join","text":"Join two index tables (see mp_index) produce ledger (see LedgerDefinition).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Join Indexes — mp_join","text":"","code":"mp_join(..., by = empty_named_list())"},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Join Indexes — mp_join","text":"... Named arguments giving indexes created mp_index another function manipulates indexes. argument become position vector used subset expand numeric vectors archetype formulas. columns use join indexes. See specify argument.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Join Indexes — mp_join","text":"two index tables passed ..., mp_join behaves much like ordinary inner join. two tables passed ..., mp_join iteratively joins pairs tables produce final ledger. example, index tables B, C passed mp_join, inner join B performed result joined C. successive internal joins. properties inner joins ensures order tables affect set rows final table (SW states without proof!). two index tables passed ..., argument just character vector column names join (standard R functions joining data frames), dot-concatenation column names. example,   two tables argument must named list character vectors, describing join columns pair tables .... names list dot-concatenations names pairs tables .... example,   columns different names two tables, can specify using formula notation left-hand-side dot-concatenation columns first table right-hand-side dot-concatenation columns second table. example,","code":"state = mp_index(   Epi = c(\"S\", \"I\", \"S\", \"I\"),   Age = c(\"young\", \"young\", \"old\", \"old\") ) mp_join(   from = mp_subset(state, Epi = \"S\"),   to = mp_subset(state, Epi = \"I\"),   by = \"Age\" ) #>     from      to #>  S.young I.young #>    S.old   I.old rates = mp_index(   Epi = c(\"lambda\", \"lambda\"),   Age = c(\"young\", \"old\") ) mp_join(   from = mp_subset(state, Epi = \"S\"),   to = mp_subset(state, Epi = \"I\"),   rate = mp_subset(rates, Epi = \"lambda\"),   by = list(     from.to = \"Age\",     from.rate = \"Age\"   ) ) #>     from      to         rate #>  S.young I.young lambda.young #>    S.old   I.old   lambda.old contact = mp_index(   AgeSusceptible = c(\"young\", \"young\", \"old\", \"old\"),   AgeInfectious = c(\"young\", \"old\", \"young\", \"old\") ) mp_join(   sus = mp_subset(state, Epi = \"S\"),   inf = mp_subset(state, Epi = \"I\"),   con = contact,   by = list(     sus.con = \"Age\" ~ \"AgeSusceptible\",     inf.con = \"Age\" ~ \"AgeInfectious\"   ) ) #>      sus     inf         con #>  S.young I.young young.young #>    S.old I.young   old.young #>  S.young   I.old   young.old #>    S.old   I.old     old.old"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Index Labels — mp_labels","title":"Index Labels — mp_labels","text":"Return character vector labels row index (ledger?? FIXME: mean ledgers??).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Index Labels — mp_labels","text":"","code":"mp_labels(x, labelling_column_names)"},{"path":"https://canmod.github.io/macpan2/reference/mp_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Index Labels — mp_labels","text":"x Object labelling_column_names index columns used generating labels. missing defaults used. (FIXME: clarify defaults used.)","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_grid.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow Diagram Grid Layout — mp_layout_grid","title":"Flow Diagram Grid Layout — mp_layout_grid","text":"Create grid layout flow diagram model specification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_grid.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow Diagram Grid Layout — mp_layout_grid","text":"","code":"mp_layout_grid(   spec,   east = \"\",   south = \"^$\",   north = \"^$\",   west = \"^$\",   loops = north,   x_gap = 0.3,   y_gap = 0.3,   north_south_sep = 0,   east_west_sep = 0,   trim_states = character() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_grid.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow Diagram Grid Layout — mp_layout_grid","text":"spec model specification made mp_tmb_model_spec related function. east Regular expression matching names flows connected eastward layout. south Regular expression matching names flows connected southward layout. north Regular expression matching names flows connected northward layout. west Regular expression matching names flows connected westward layout. loops Regular expression matching names flows cause loops flow model, ignored building layout. x_gap Size gap left right 1--1 space provided node. y_gap Size gap 1--1 space provided node. north_south_sep Horizontal separation north south flow arrows. east_west_sep Vertical separation east west flow arrows. trim_states List states remove diagram","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_paths.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow Diagram Grid Layout — mp_layout_paths","title":"Flow Diagram Grid Layout — mp_layout_paths","text":"Layout flow diagram model specification row one paths model (ignoring loops).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_paths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow Diagram Grid Layout — mp_layout_paths","text":"","code":"mp_layout_paths(   spec,   sort_paths = TRUE,   combine_columns = TRUE,   deduplicate_edges = TRUE,   loops = \"^$\",   ignore = \"^$\",   x_gap = 0.3,   y_gap = 0.3,   north_south_sep = 0,   east_west_sep = 0,   trim_states = character() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_paths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow Diagram Grid Layout — mp_layout_paths","text":"spec model specification made mp_tmb_model_spec related function. sort_paths paths/rows sorted minimize number times edge must go node connected ? combine_columns state/node get column layout (FALSE) algorithm try place branching states column (TRUE, default). deduplicate_edges row edges path duplicate edges removed? loops Regular expression matching names flows cause loops flow model, ignored building layout. ignore Regular expression matching names flows removed layout analysis entirely. isolated data frame custom drawing 'difficult' edges. x_gap Size gap left right 1--1 space provided node. y_gap Size gap 1--1 space provided node. north_south_sep Horizontal separation north south flow arrows. east_west_sep Vertical separation east west flow arrows. trim_states List states remove diagram","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_ledgers.html","id":null,"dir":"Reference","previous_headings":"","what":"Bundle up Ledgers — mp_ledgers","title":"Bundle up Ledgers — mp_ledgers","text":"Bundle several ledgers (see LedgerDefinition) pass mp_dynamic_model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_ledgers.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Bundle up Ledgers — mp_ledgers","text":"","code":"mp_ledgers(...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_ledgers.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Bundle up Ledgers — mp_ledgers","text":"... Ledgers bundle .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_linear.html","id":null,"dir":"Reference","previous_headings":"","what":"Linear Chain Product — mp_linear","title":"Linear Chain Product — mp_linear","text":"TODO: mean?","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_linear.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Linear Chain Product — mp_linear","text":"","code":"mp_linear(x, y_labelling_column_names)"},{"path":"https://canmod.github.io/macpan2/reference/mp_linear.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Linear Chain Product — mp_linear","text":"x index. y_labelling_column_names TODO","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_lookup.html","id":null,"dir":"Reference","previous_headings":"","what":"Lookup — mp_lookup","title":"Lookup — mp_lookup","text":"Lookup subset factor index associated symbol, return index associated symbol.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_lookup.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Lookup — mp_lookup","text":"","code":"mp_lookup(index, symbol)"},{"path":"https://canmod.github.io/macpan2/reference/mp_lookup.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Lookup — mp_lookup","text":"index Index table (see mp_index). symbol Character string possibly associated subset factor index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_model_starter.html","id":null,"dir":"Reference","previous_headings":"","what":"Model Starter — mp_model_starter","title":"Model Starter — mp_model_starter","text":"Create directory template model definition.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_model_starter.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model Starter — mp_model_starter","text":"","code":"mp_model_starter(starter_name, dir)"},{"path":"https://canmod.github.io/macpan2/reference/mp_model_starter.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model Starter — mp_model_starter","text":"starter_name Currently can sir. dir String giving path directory copying template model definition.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":null,"dir":"Reference","previous_headings":"","what":"Optimize — mp_optimize","title":"Optimize — mp_optimize","text":"Optimize","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Optimize — mp_optimize","text":"","code":"mp_optimize(model, optimizer, ...)  # S3 method for class 'TMBCalibrator' mp_optimize(model, optimizer = c(\"nlminb\", \"optim\"), ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Optimize — mp_optimize","text":"model model object capable optimized. See model types supported. optimizer Name implemented optimizer. See options type model. ... Arguments pass optimizer.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Optimize — mp_optimize","text":"output optimizer. model object modified saves history optimization outputs. outputs can obtained using mp_optimizer_output.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"methods-by-class-","dir":"Reference","previous_headings":"","what":"Methods (by class)","title":"Optimize — mp_optimize","text":"mp_optimize(TMBCalibrator): Optimize TMB calibrator.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":null,"dir":"Reference","previous_headings":"","what":"Optimizer Output — mp_optimizer_output","title":"Optimizer Output — mp_optimizer_output","text":"Get output optimizer used model calibration.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Optimizer Output — mp_optimizer_output","text":"","code":"mp_optimizer_output(model, what = c(\"latest\", \"all\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Optimizer Output — mp_optimizer_output","text":"model object optimized. string indicating whether return results \"latest\" optimization attempt list \"\" .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Optimizer Output — mp_optimizer_output","text":"objects created mp_tmb_calibrator successfully passed mp_optimize, build optimization history. history recorded list output produced underlying optimizer (e.g. nlminb). mp_optimizer_output function returns latest output default entire history list.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_par.html","id":null,"dir":"Reference","previous_headings":"","what":"Fit Parameters — mp_par","title":"Fit Parameters — mp_par","text":"Define prior distributions parameters random effects passed par argument mp_tmb_calibrator function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_par.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fit Parameters — mp_par","text":"","code":"mp_par(param, random)"},{"path":"https://canmod.github.io/macpan2/reference/mp_par.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fit Parameters — mp_par","text":"param Named list distributional specifications fixed effects. random Named list distributional specifications random effects.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow — mp_per_capita_flow","title":"Flow — mp_per_capita_flow","text":"Specify different kinds flows compartments.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow — mp_per_capita_flow","text":"","code":"mp_per_capita_flow(from, to, rate, abs_rate = NULL)  mp_per_capita_inflow(from, to, rate, abs_rate = NULL)  mp_per_capita_outflow(from, rate, abs_rate = NULL)  mp_absolute_flow(from, to, rate, rate_name = NULL)"},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow — mp_per_capita_flow","text":"String giving name compartment flow originates. String giving name compartment flow going. rate String giving expression per-capita absolute flow rate. Alternatively per-capita flows, back compatibility, two-sided formula left-hand-side giving name absolute flow rate per unit time-stepand right-hand-side giving expression per-capita rate flow . abs_rate String giving name absolute flow rate, computed * rate. formula passed rate (recommended), abs_rate argument ignored. rate_name String giving name absolute flow rate.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Flow — mp_per_capita_flow","text":"examples can mixed matched mp_tmb_model_spec() produce compartmental models. Note symbols used must used appropriate context (e.g., N used total population size, must expression like N ~ S + + R somewhere model models constant population size must default variable, N, numerical value).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Flow — mp_per_capita_flow","text":"mp_per_capita_inflow(): flow compartment, flow compartment. compartment can even function set compartments, updated. common construction mp_per_capita_inflow(\"N\", \"S\", \"birth_rate\", \"birth\") adding birth process, involves total population size, N, rather single compartment. mp_per_capita_outflow(): flow compartment, without going anywhere. useful removing individuals system (e.g., death). keep track total number dead individuals one can use mp_per_capita_flow set compartment individuals (e.g., = \"D\"). mp_absolute_flow(): Experimental","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Flow — mp_per_capita_flow","text":"","code":"# infection by mass action # https://github.com/canmod/macpan2/blob/main/inst/starter_models/si mp_per_capita_flow(\"S\", \"I\", \"beta * I / N\", \"infection\") #> From: S #> To: I #> Per-capita rate expression: beta * I/N #> Absolute rate symbol: infection  # recovery # https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir mp_per_capita_flow(\"I\", \"R\", \"gamma\", \"recovery\") #> From: I #> To: R #> Per-capita rate expression: gamma #> Absolute rate symbol: recovery  # disease progression with different severity # https://github.com/canmod/macpan2/blob/main/inst/starter_models/macpan_base mp_per_capita_flow(\"E\", \"I_mild\", \"alpha * phi\"      , \"progression_mild\") #> From: E #> To: I_mild #> Per-capita rate expression: alpha * phi #> Absolute rate symbol: progression_mild mp_per_capita_flow(\"E\", \"I_sev\" , \"alpha * (1 - phi)\", \"progression_sev\") #> From: E #> To: I_sev #> Per-capita rate expression: alpha * (1 - phi) #> Absolute rate symbol: progression_sev  # birth # https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir_demog mp_per_capita_inflow(\"N\", \"S\", \"nu\", \"birth\") #> From: N #> To: S #> Per-capita rate expression: nu #> Absolute rate symbol: birth  # death # https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir_demog mp_per_capita_outflow(\"S\", \"mu\", \"death_S\") #> From: S #> Per-capita rate expression: mu #> Absolute rate symbol: death_S mp_per_capita_outflow(\"I\", \"mu\", \"death_I\") #> From: I #> Per-capita rate expression: mu #> Absolute rate symbol: death_I mp_per_capita_outflow(\"R\", \"mu\", \"death_R\") #> From: R #> Per-capita rate expression: mu #> Absolute rate symbol: death_R  # vaccination  # https://github.com/canmod/macpan2/blob/main/inst/starter_models/shiver mp_per_capita_flow(\"S\", \"V\", \"((a * S)/(b + S))/S\",  \"vaccination\") #> From: S #> To: V #> Per-capita rate expression: ((a * S)/(b + S))/S #> Absolute rate symbol: vaccination  # importation (experimental) # mp_absolute_inflow(\"I\", \"delta\", \"importation\")"},{"path":"https://canmod.github.io/macpan2/reference/mp_positions.html","id":null,"dir":"Reference","previous_headings":"","what":"Position Vectors — mp_positions","title":"Position Vectors — mp_positions","text":"Return integer vector positions x table. Currently simple wrapper around match.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_positions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Position Vectors — mp_positions","text":"","code":"mp_positions(x, table, zero_based = TRUE)"},{"path":"https://canmod.github.io/macpan2/reference/mp_positions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Position Vectors — mp_positions","text":"x Character vector table Character vector zero_based Use zero-based indexing? Defaults TRUE, otherwise standard R one-based indexing used.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rbf.html","id":null,"dir":"Reference","previous_headings":"","what":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","title":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","text":"Pass output function tv argument mp_tmb_calibrator model time variation parameter flexible radial basis functions.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rbf.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","text":"","code":"mp_rbf(   tv,   dimension,   initial_weights,   seed,   prior_sd = 1,   fit_prior_sd = TRUE,   sparse_tol = 0.01 )"},{"path":"https://canmod.github.io/macpan2/reference/mp_rbf.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","text":"tv String giving name parameter. dimension Number bases. initial_weights Optional vector dimensions elements. parameters fitted determine tv varies time. seed Optional random seed use generate initial_weights provided. prior_sd Prior standard deviation default value radial basis function coefficients, defaults 1. fit_prior_sd prior sd fitted. sparse_tol Tolerance radial basis function outputs set exactly zero. Small values accurate slower. Lack accuracy can visually apparent jumps graphs time-varying parameter.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reduce.html","id":null,"dir":"Reference","previous_headings":"","what":"Reduce Model — mp_reduce","title":"Reduce Model — mp_reduce","text":"Reduce model removing model structure (e.g. mp_per_capita_flow), expression lists plain R formulas.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reduce.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reduce Model — mp_reduce","text":"","code":"mp_reduce(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_reduce.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reduce Model — mp_reduce","text":"model model object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reference.html","id":null,"dir":"Reference","previous_headings":"","what":"Reference Index — mp_reference","title":"Reference Index — mp_reference","text":"Extract index used reference generating position vectors.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reference.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reference Index — mp_reference","text":"","code":"mp_reference(x, dimension_name)"},{"path":"https://canmod.github.io/macpan2/reference/mp_reference.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reference Index — mp_reference","text":"x Object dimension_name Name dimension used ledger applicable.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rename.html","id":null,"dir":"Reference","previous_headings":"","what":"Rename Index Columns — mp_rename","title":"Rename Index Columns — mp_rename","text":"Rename Index Columns","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rename.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Rename Index Columns — mp_rename","text":"","code":"mp_rename(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_rename.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Rename Index Columns — mp_rename","text":"x index columns renamed. ... Name-value pairs. name gives new name value character vector giving old name.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_sim_bounds.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulation Bounds (Experimental) — mp_sim_bounds","title":"Simulation Bounds (Experimental) — mp_sim_bounds","text":"Set simulation bounds (start time end time) calibration. used override default simulation bounds taken observed data passed mp_tmb_calibrator. first date first simulated time step (chosen first data point infectious individuals can built ) second date last simulated time step (chosen last data point can forecast period). last argument gives scale single time step (case always daily).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_sim_bounds.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulation Bounds (Experimental) — mp_sim_bounds","text":"","code":"mp_sim_bounds(sim_start, sim_end, time_scale)"},{"path":"https://canmod.github.io/macpan2/reference/mp_sim_bounds.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulation Bounds (Experimental) — mp_sim_bounds","text":"sim_start Start time simulation. sim_end End time simulation. time_scale Qualitative description size time step. currently \"steps\", \"daily\", \"weekly\" allowed, \"steps\" recommended version two poorly tested throw warning. recommended \"steps\" option assumes positive integers used indicate particular point simulation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_simulator.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulator — mp_simulator","title":"Simulator — mp_simulator","text":"Construct simulator model specification object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_simulator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulator — mp_simulator","text":"","code":"mp_simulator(model, time_steps, outputs, default = list())"},{"path":"https://canmod.github.io/macpan2/reference/mp_simulator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulator — mp_simulator","text":"model model specification object. time_steps many time steps simulated simulations requested? outputs Character vector names model quantities outputted simulations requested. default Named list numerical objects update default values defined model specification object. number objects can updated .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_slices.html","id":null,"dir":"Reference","previous_headings":"","what":"Slice an index — mp_slices","title":"Slice an index — mp_slices","text":"Slice index","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_slices.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Slice an index — mp_slices","text":"","code":"mp_slices(index, unpack = c(\"no\", \"maybe\", \"yes\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_slices.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Slice an index — mp_slices","text":"index Index slice . unpack Place factors global environment?","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_square.html","id":null,"dir":"Reference","previous_headings":"","what":"Self Cartesian Product — mp_square","title":"Self Cartesian Product — mp_square","text":"Self Cartesian Product","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_square.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Self Cartesian Product — mp_square","text":"","code":"mp_square(x, suffixes = c(\"A\", \"B\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_square.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Self Cartesian Product — mp_square","text":"x index. suffixes Length-2 character vector giving suffixes disambiguate column names output.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_state_dependence_frame.html","id":null,"dir":"Reference","previous_headings":"","what":"State Dependence Frame — mp_state_dependence_frame","title":"State Dependence Frame — mp_state_dependence_frame","text":"Data frame giving states per-capita flow rates directly depend . intended plotting diagrams mathematical analysis, describe indirect dependence flow rates state variables.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_dependence_frame.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"State Dependence Frame — mp_state_dependence_frame","text":"","code":"mp_state_dependence_frame(spec)"},{"path":"https://canmod.github.io/macpan2/reference/mp_state_dependence_frame.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"State Dependence Frame — mp_state_dependence_frame","text":"spec Model specification spec.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":null,"dir":"Reference","previous_headings":"","what":"State Variables — mp_state_vars","title":"State Variables — mp_state_vars","text":"Get state variables model specification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"State Variables — mp_state_vars","text":"","code":"mp_state_vars(spec)"},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"State Variables — mp_state_vars","text":"spec Model specification (mp_tmb_model_spec).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"State Variables — mp_state_vars","text":"Character vector names state variables explicitly represented model using functions like mp_per_capita_flow.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":null,"dir":"Reference","previous_headings":"","what":"Structured Vectors — mp_structured_vector","title":"Structured Vectors — mp_structured_vector","text":"documentation originally mp_index() cleaned See issue #131. Also experimental feature.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Structured Vectors — mp_structured_vector","text":"","code":"mp_structured_vector(x, ...)  mp_set_numbers(vector, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Structured Vectors — mp_structured_vector","text":"x index. ... Passed S3 methods. vector index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Structured Vectors — mp_structured_vector","text":"mp_set_numbers(): Update numerical values structured vector. TODO: details syntax.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Structured Vectors — mp_structured_vector","text":"","code":"state = mp_index(   Epi = c(\"S\", \"I\", \"S\", \"I\"),   Age = c(\"young\", \"young\", \"old\", \"old\") ) state_vector = (state   |> mp_structured_vector()   |> mp_set_numbers(Epi = c(S = 1000))   |> mp_set_numbers(Epi = c(I = 1), Age = \"old\") ) print(state_vector) #> S.young I.young   S.old   I.old  #>    1000       0    1000       1"},{"path":"https://canmod.github.io/macpan2/reference/mp_subset.html","id":null,"dir":"Reference","previous_headings":"","what":"Subset of Indexes — mp_subset","title":"Subset of Indexes — mp_subset","text":"Take subset rows index table (see mp_index) produce another index table. mp_subset function gives rows match certain criterion mp_setdiff gives rows match.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_subset.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Subset of Indexes — mp_subset","text":"","code":"mp_subset(x, ...)  mp_setdiff(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_subset.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Subset of Indexes — mp_subset","text":"x Model index. ... Name-value pairs. names columns (sets columns using dot-concatenation) x values character vectors refer labels respect columns. values determine resulting subset.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_symmetric.html","id":null,"dir":"Reference","previous_headings":"","what":"Symmetric Self Cartesian Product — mp_symmetric","title":"Symmetric Self Cartesian Product — mp_symmetric","text":"Symmetric Self Cartesian Product","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_symmetric.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Symmetric Self Cartesian Product — mp_symmetric","text":"","code":"mp_symmetric(x, y_labelling_column_names, exclude_diag = TRUE)"},{"path":"https://canmod.github.io/macpan2/reference/mp_symmetric.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Symmetric Self Cartesian Product — mp_symmetric","text":"x index. y_labelling_column_names TODO exclude_diag 'diagonal' commponents excluded output.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_time_scale.html","id":null,"dir":"Reference","previous_headings":"","what":"Time Scale — mp_time_scale","title":"Time Scale — mp_time_scale","text":"Time Scale","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_time_scale.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Time Scale — mp_time_scale","text":"","code":"mp_time_scale(start, end, time_step_scale = c(\"steps\", \"daily\", \"weekly\"), ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_time_scale.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Time Scale — mp_time_scale","text":"start First date time first time step end Last date time last time step time_step_scale TODO ... TODO","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb.html","id":null,"dir":"Reference","previous_headings":"","what":"Get Underlying TMB Object — mp_tmb","title":"Get Underlying TMB Object — mp_tmb","text":"Get result TMB::MakeADFun underlying TMB-based model macpan2.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get Underlying TMB Object — mp_tmb","text":"","code":"mp_tmb(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get Underlying TMB Object — mp_tmb","text":"model object based TMB.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":null,"dir":"Reference","previous_headings":"","what":"Make TMB Calibrator — mp_tmb_calibrator","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"Construct object can get used calibrate object produced mp_tmb_model_spec mp_tmb_library, possibly modified mp_tmb_insert mp_tmb_update.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"","code":"mp_tmb_calibrator(   spec,   data,   traj,   par,   tv = character(),   outputs = traj,   default = list(),   time = NULL )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"spec TMB model spec fit data. specs can produced mp_tmb_model_spec mp_tmb_library, possibly modified mp_tmb_insert mp_tmb_update. data data frame containing trajectories fit possibly time-varying parameters. data must format produced mp_trajectory. traj character vector giving names trajectories fit data, named list likelihood distributions specified distribution trajectory. par character vector giving names parameters, either time-varying , fit using trajectory match. tv character vector giving names parameters make time-varying according values data, radial basis function specified mp_rbf. outputs character vector outputs generated mp_trajectory, mp_trajectory_sd, mp_trajectory_ensemble called optimized calibrator. default just trajectories listed traj. default list default values use update defaults spec. default nothing updated. Alternatively one use mp_tmb_update update spec outside function. Indeed approach necessary new expressions, addition default updates, need added spec (e.g. seasonally varying transmission). time Specify start end time simulated trajectories, time period associated time step. Currently valid choice NULL, takes simulation bounds data.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"","code":"spec = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") sim = mp_simulator(spec, 50, \"infection\") data = mp_trajectory(sim) cal = mp_tmb_calibrator(     spec   , data   , traj = \"infection\"   , par = \"beta\"   , default = list(beta = 0.25) ) mp_optimize(cal) #> outer mgc:  389.7835  #> outer mgc:  259.2344  #> outer mgc:  40.03711  #> outer mgc:  1.594322  #> outer mgc:  0.002775624  #> outer mgc:  8.4447e-09  #> $par #> params  #>    0.2  #>  #> $objective #> [1] 49.74796 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 5 #>  #> $evaluations #> function gradient  #>        6        6  #>  #> $message #> [1] \"relative convergence (4)\" #>  mp_tmb_coef(cal)  ## requires broom.mixed package #> outer mgc:  8.4447e-09  #> outer mgc:  11.74622  #> outer mgc:  12.05664  #> outer mgc:  31.01941  #>     term  mat row col default  type estimate   std.error #> 1 params beta   0   0    0.25 fixed      0.2 0.009166433"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":null,"dir":"Reference","previous_headings":"","what":"TMB Model Coefficient Table — mp_tmb_coef","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"TMB Model Coefficient Table","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"","code":"mp_tmb_coef(model, back_transform = TRUE, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"model Object contains information model coefficients. back_transform boolean indicate model coefficients back transformed display defaults, estimates, confidence intervals original scale. Coefficient names also stripped transformation identifier. Currently, back transformation applies log transformed coefficients named \"log_\" prefix logit transformed coefficients named \"logit_\" prefix. Back transformation also applies time varying parameters distributional parameters get automatic prefixes used. back_transform defaults TRUE. ... Arguments pass onto broom.mixed::tidy.TMB method.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"data frame describes fitted coefficients.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":null,"dir":"Reference","previous_headings":"","what":"Expression List — mp_tmb_expr_list","title":"Expression List — mp_tmb_expr_list","text":"Create list expressions defining compartmental model TMB.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Expression List — mp_tmb_expr_list","text":"","code":"mp_tmb_expr_list(   before = list(),   during = list(),   after = list(),   .simulate_exprs = character(0L) )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Expression List — mp_tmb_expr_list","text":"List formulas evaluated order provided simulation loop begins. formula must left hand side gives name matrix updated, right hand side giving expression containing names matrices model, functions defined macpan2.cpp, numerical literals (e.g. 3.14). available functions described engine_functions. Names can provided components , names unique.  names used .simulate_exprs argument. List formulas evaluated every iteration simulation loop, rules . List formulas evaluated simulation loop, rules . .simulate_exprs Character vector names expressions evaluated within TMB simulate blocks. useful expression evaluated computation objective function gradients (e.g. expression contains randomness discontinuities break automatic differentiation machinery TMB).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Expression List — mp_tmb_expr_list","text":"Object class ExprList following methods.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"Expression List — mp_tmb_expr_list","text":"$data_arg(...): Return following components data structure pass C++. expr_output_id – Indices list matrices identifying matrix produced. expr_sim_block – Identified whether expression evaluated inside simulate macro within TMB. expr_num_p_table_rows – Number rows associated expression parse table (p_table_*) eval_schedule – Vector giving number expressions evaluate phase (, , ) simulation. p_table_x – Parse table column giving index looking either function, matrix, literal. p_table_n – Parse table column giving number arguments functions. p_table_i – Parse table column giving indices looking rows parse table corresponding first argument function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"method-arguments","dir":"Reference","previous_headings":"","what":"Method Arguments","title":"Expression List — mp_tmb_expr_list","text":"...: Character vector containing names matrices model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":null,"dir":"Reference","previous_headings":"","what":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"Covariance Fixed Effect Estimates","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"","code":"mp_tmb_fixef_cov(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"model Object contains information fitted model parameters.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"covariance matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":null,"dir":"Reference","previous_headings":"","what":"Modify a TMB Model Spec — mp_tmb_insert","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"Insert, update, delete elements TMB model spec, produced using mp_tmb_library mp_tmb_model_spec, mp_tmb_delete. difference mp_tmb_insert mp_tmb_update former shifts positions existing expressions make room new expressions, whereas latter overwrites existing expressions using new expressions. treatment new default values integers . examples clarify difference. Note mp_tmb_delete contain expressions argument, necessary specify new expressions case deletion.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"","code":"mp_tmb_insert(   model,   phase = \"during\",   at = 1L,   expressions = list(),   default = list(),   integers = list(),   must_save = character(),   must_not_save = character(),   sim_exprs = character() )  mp_tmb_update(   model,   phase = \"during\",   at = 1L,   expressions = list(),   default = list(),   integers = list(),   must_save = character(),   must_not_save = character(),   sim_exprs = character() )  mp_tmb_delete(   model,   phase,   at,   default = character(),   integers = character(),   must_save = character(),   must_not_save = character(),   sim_exprs = character() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"model TMB model spec object produced using mp_tmb_library mp_tmb_model_spec. phase phase expressions inserted, updated, deleted. Expression number, can identified printing model, expressions inserted updated. inserted existing expressions number higher shifted new expressions added. updated, existing expressions number + length(expressions) - 1 replaced new expressions. mp_tmb_delete, numeric vector integers identifying expressions delete model. expressions Expressions insert model spec replace existing expressions. default Named list objects, can coerced numeric matrix. names refer variables appear , , . mp_tmb_delete, character vector objects delete model. integers Named list vectors can coerced integer vectors. integer vectors can used name model formulas provide indexing matrices grouping factors group_sums. mp_tmb_delete, character vector objects delete model. must_save Character vector names matrices must values stored every iteration simulation loop. example, matrix user want returned impacts dynamics time lag must saved therefore list. must_not_save Character vector names matrices must values stored every iteration simulation loop. example, user may ask return large matrix create performance issues stored iteration. creator model can mark matrices making impossible user model save full simulation history. sim_exprs Character vector names , , expressions must evaluated simulations produced objective function evaluated. example, expressions generate stochasticity listed sim_exprs TMB objective functions must continuous.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"new model spec object updated /inserted information.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"modifications update model specification -place. Instead output mp_tmb_insert, mp_tmb_update, mp_tmb_delete define new model specification saved want use new model (e.g., new_model = mp_tmb_insert(model, ...)).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"","code":"si = mp_tmb_library(\"starter_models\", \"si\", package = \"macpan2\") print(si) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       N         100.0 #>    beta           0.2 #>       I           1.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  #>      abs_rate = \"infection\") #>   ## Update the mixing process to include  ## optional phenomenological heterogeneity. ## We need mp_tmb_update here so that  ## the previous infection expression is ## overwritten. mp_tmb_update(si, phase = \"during\"   , at = 1   , expressions = list(infection ~ beta * I * (S/N)^zeta)   , default = list(zeta = 1) ) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       N         100.0 #>    beta           0.2 #>       I           1.0 #>    zeta           1.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ beta * I * (S/N)^zeta #>   ## Parameterize with log_beta in place of beta. ## We need mp_tmb_insert here so that the ## existing expression for computing the initial ## number of susceptible indiviudals is not ## overwritten. mp_tmb_insert(si, phase = \"before\"   , at = 1   , expressions = list(beta ~ exp(log_beta))   , default = list(log_beta = log(0.5)) ) #> --------------------- #> Default values: #> --------------------- #>    matrix row col       value #>         N         100.0000000 #>      beta           0.2000000 #>         I           1.0000000 #>  log_beta          -0.6931472 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: beta ~ exp(log_beta) #> 2: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  #>      abs_rate = \"infection\") #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert_reports.html","id":null,"dir":"Reference","previous_headings":"","what":"Insert Reports — mp_tmb_insert_reports","title":"Insert Reports — mp_tmb_insert_reports","text":"version mp_tmb_insert making convenient transform incidence variable reports variable, accounts reporting delays -reporting. new reports variable convolution simulation history incidence variable kernel proportional Gamma distribution reporting delay times.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert_reports.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Insert Reports — mp_tmb_insert_reports","text":"","code":"mp_tmb_insert_reports(   model,   incidence_name,   report_prob,   mean_delay,   cv_delay,   reports_name = sprintf(\"reported_%s\", incidence_name),   report_prob_name = sprintf(\"%s_report_prob\", incidence_name),   mean_delay_name = sprintf(\"%s_mean_delay\", incidence_name),   cv_delay_name = sprintf(\"%s_cv_delay\", incidence_name) )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert_reports.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Insert Reports — mp_tmb_insert_reports","text":"model model produced mp_tmb_model_spec. incidence_name Name incidence variable transformed. report_prob Value use reporting probability; proportion cases get reported. mean_delay Mean Gamma distribution reporting delay times. cv_delay Coefficient variation Gamma distribution reporting delay times. reports_name Name new reports variable. report_prob_name Name variable containing report_prob. mean_delay_name Name variable containing mean_delay. cv_delay_name Name variable containing cv_delay.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":null,"dir":"Reference","previous_headings":"","what":"TMB Library — mp_tmb_library","title":"TMB Library — mp_tmb_library","text":"Get TMB model specification model library.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"TMB Library — mp_tmb_library","text":"","code":"mp_tmb_library(..., package = NULL, alternative_specs = FALSE)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"TMB Library — mp_tmb_library","text":"... File path components pointing directory contains R script creates object called spec, produced mp_tmb_model_spec. package NULL, file.path used put together ... components package name package (character string) system.file used put together ... components. alternative_specs TRUE, return list alternative specification objects. models without alternatives cause return value list one element containing spec object.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"TMB Library — mp_tmb_library","text":"","code":"mp_tmb_library(     \"starter_models\"   , \"si\"   , package = \"macpan2\" ) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       N         100.0 #>    beta           0.2 #>       I           1.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  #>      abs_rate = \"infection\") #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_model_spec.html","id":null,"dir":"Reference","previous_headings":"","what":"Specify a TMB Model — mp_tmb_model_spec","title":"Specify a TMB Model — mp_tmb_model_spec","text":"Specify model TMB engine.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_model_spec.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Specify a TMB Model — mp_tmb_model_spec","text":"","code":"mp_tmb_model_spec(   before = list(),   during = list(),   after = list(),   default = list(),   integers = list(),   must_save = character(),   must_not_save = character(),   sim_exprs = character(),   state_update = c(\"euler\", \"rk4\", \"euler_multinomial\", \"hazard\") )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_model_spec.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Specify a TMB Model — mp_tmb_model_spec","text":"List formulas evaluated (order provided) simulation loop begins. formula must left hand side gives name matrix updated, right hand side giving expression containing names matrices model, functions defined TMB engine, numerical literals (e.g. 3.14). available functions TMB engine  can described engine_functions. Names can provided components , names unique. names used sim_exprs argument. List formulas evaluated every iteration simulation loop, rules . List formulas evaluated simulation loop, rules . default Named list objects, can coerced numeric matrix. names refer variables appear , , . integers Named list vectors can coerced integer vectors. integer vectors can used name model formulas provide indexing matrices grouping factors group_sums. must_save Character vector names matrices must values stored every iteration simulation loop. example, matrix user want returned impacts dynamics time lag must saved therefore list. must_not_save Character vector names matrices must values stored every iteration simulation loop. example, user may ask return large matrix create performance issues stored iteration. creator model can mark matrices making impossible user model save full simulation history. sim_exprs Character vector names , , expressions must evaluated simulations produced objective function evaluated. example, expressions generate stochasticity listed sim_exprs TMB objective functions must continuous. state_update (experimental) Optional character vector update state variables relevant. Options include \"euler\", \"rk4\", \"euler_multinomial\".","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmbstan_coef.html","id":null,"dir":"Reference","previous_headings":"","what":"Model Coefficient Table with stan — mp_tmbstan_coef","title":"Model Coefficient Table with stan — mp_tmbstan_coef","text":"Leverages tmbstan broom.mixed packages generate MCMC-based coefficient tables.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmbstan_coef.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model Coefficient Table with stan — mp_tmbstan_coef","text":"","code":"mp_tmbstan_coef(model, tmbstan_args = list(), ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmbstan_coef.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model Coefficient Table with stan — mp_tmbstan_coef","text":"model Object contains information model coefficients. tmbstan_args Arguments pass tmbstan, used generate rstan object underlying TMB object. ... Arguments pass onto broom.mixed::tidy.stanfit method.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_traj.html","id":null,"dir":"Reference","previous_headings":"","what":"Trajectory Specification — mp_traj","title":"Trajectory Specification — mp_traj","text":"Specify set trajectories fit. output function intended passed traj argument mp_tmb_calibrator.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_traj.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Trajectory Specification — mp_traj","text":"","code":"mp_traj(likelihood = list(), condensation = list())"},{"path":"https://canmod.github.io/macpan2/reference/mp_traj.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Trajectory Specification — mp_traj","text":"likelihood List likelihood components. names list identify trajectory associated likelihood component. condensation List condensation methods. names list identify trajectories produced condensation method.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":null,"dir":"Reference","previous_headings":"","what":"Trajectory — mp_trajectory","title":"Trajectory — mp_trajectory","text":"Return simulations trajectory output variables dynamical model simulator. see functionality context, please see vignette(\"quickstart\").","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Trajectory — mp_trajectory","text":"","code":"mp_trajectory(model, include_initial = FALSE)  mp_trajectory_sd(model, conf.int = FALSE, conf.level = 0.95)  mp_trajectory_ensemble(model, n, probs = c(0.025, 0.975))  mp_trajectory_sim(model, n, probs = c(0.025, 0.25, 0.5, 0.75, 0.975))  mp_trajectory_replicate(model, n)"},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Trajectory — mp_trajectory","text":"model dynamical model simulator produced mp_simulator. include_initial initial values simulation included output? TRUE include outputs time == 0 associated initial values. See mp_initial another approach getting initial values. conf.int confidence intervals produced? conf.level conf.int TRUE, confidence level used?  example, default 0.95 corresponds 95% confidence intervals. n Number random trajectories simulate. probs Numeric vector probabilities corresponding quantiles summarizing results random realizations.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Trajectory — mp_trajectory","text":"data frame one row simulated value following columns. matrix Name variable model. variables matrix-valued macpan2 (scalars technically 1--1 matrices), explains name field. hindsight called variable. time Time index simulated value, time = 0 indicating initial values. row 0-based index row matrix, name row matrix row names (names column vectors) supplied default value matrix. col 0-based index column matrix, name column matrix column names supplied default value matrix. also possible column blank everything either scalar column vector (common case). value (mp_trajectory mp_trajectory_sd) Simulation values. sd (mp_trajectory_sd ) standard deviations simulated values accounting parameter estimation uncertainty. conf.low (mp_trajectory_sd ) lower bounds confidence interval simulated values. conf.high (mp_trajectory_sd ) upper bounds confidence interval simulated values. n% (mp_trajectory_[ensemble|sim]) n-th quantiles simulation values repeated simulations.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Trajectory — mp_trajectory","text":"mp_trajectory_sd(): Simulate trajectory includes uncertainty information provided sdreport function TMB default settings. mp_trajectory_ensemble(): Simulate trajectory includes uncertainty information provided repeatedly sampling normal approximation distribution fitted parameters, generating one trajectory samples. quantiles empirical distribution trajectories can used produce confidence interval fitted trajectory. mp_trajectory_sim(): Generate quantiles n realizations trajectory. Instead value column output data frame, one column quantiles defined probs. mp_trajectory_replicate(): Generate list n simulation results.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Trajectory — mp_trajectory","text":"","code":"spec = mp_tmb_library(\"starter_models\"   , \"si\"   , package = \"macpan2\" ) simulator = mp_simulator(spec   , time_steps = 10L   , outputs = c(\"infection\", \"I\") ) trajectory = mp_trajectory(simulator) print(trajectory) #>       matrix time row col     value #> 1          I    1   0   0 1.1980000 #> 2  infection    1   0   0 0.1980000 #> 3          I    2   0   0 1.4347296 #> 4  infection    2   0   0 0.2367296 #> 5          I    3   0   0 1.7175586 #> 6  infection    3   0   0 0.2828290 #> 7          I    4   0   0 2.0551703 #> 8  infection    4   0   0 0.3376117 #> 9          I    5   0   0 2.4577569 #> 10 infection    5   0   0 0.4025866 #> 11         I    6   0   0 2.9372272 #> 12 infection    6   0   0 0.4794702 #> 13         I    7   0   0 3.5074180 #> 14 infection    7   0   0 0.5701908 #> 15         I    8   0   0 4.1842977 #> 16 infection    8   0   0 0.6768796 #> 17         I    9   0   0 4.9861405 #> 18 infection    9   0   0 0.8018428 #> 19         I   10   0   0 5.9336454 #> 20 infection   10   0   0 0.9475049"},{"path":"https://canmod.github.io/macpan2/reference/mp_triangle.html","id":null,"dir":"Reference","previous_headings":"","what":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","title":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","text":"Self Cartesian Product Excluding One -Diagonal Side","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_triangle.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","text":"","code":"mp_triangle(   x,   y_labelling_column_names,   exclude_diag = TRUE,   lower_tri = FALSE )"},{"path":"https://canmod.github.io/macpan2/reference/mp_triangle.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","text":"x index. y_labelling_column_names TODO exclude_diag 'diagonal' commponents excluded output. lower_tri lower triangular components include output. FALSE result upper triangular.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_union.html","id":null,"dir":"Reference","previous_headings":"","what":"Union of Indexes — mp_union","title":"Union of Indexes — mp_union","text":"Union Indexes","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_union.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Union of Indexes — mp_union","text":"","code":"mp_union(...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_union.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Union of Indexes — mp_union","text":"... Indexes.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_zero_vector.html","id":null,"dir":"Reference","previous_headings":"","what":"Zero Vector — mp_zero_vector","title":"Zero Vector — mp_zero_vector","text":"Create numeric vector zeros names given x","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_zero_vector.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Zero Vector — mp_zero_vector","text":"","code":"mp_zero_vector(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_zero_vector.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Zero Vector — mp_zero_vector","text":"x Object representing names output vector. commonly character vector. ... Passed S3 methods.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Names and Labels — names_and_labels","title":"Names and Labels — names_and_labels","text":"page describes functions giving names labels entities structured models.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names and Labels — names_and_labels","text":"","code":"to_labels(x)  to_names(x)  to_name(x)  to_name_pairs(x)  to_values(x)"},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names and Labels — names_and_labels","text":"x Object extract name, names, labels, name-pairs, values. types objects work functions.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Names and Labels — names_and_labels","text":"Character vector (numeric vector case to_values) describes x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Names and Labels — names_and_labels","text":"to_labels(): Extract vector describing rows data frame values numeric vector. to_names(): Extract character vector describing character-valued columns data frame flattened structure numeric vector. Names obey following restrictions:  (1) dots, (2) values must start letter, (3) characters must letters, numbers, underscore. to_name(): Extract string (.e. length-1 character vector) describing character-valued columns data frame flattened structure numeric vector. name object dot-concatenation names. to_name_pairs(): character vector possible pairwise dot-concatenations set names. to_values(): Extract numeric column data frame single numerical column. data frame might one column, one can numeric. function also turn numeric matrix array objects dimnames flattened numeric vector labels produced appropriately dot-concatenating dimnames.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"context","dir":"Reference","previous_headings":"","what":"Context","title":"Names and Labels — names_and_labels","text":"goal macpan2 provide mechanism representing structured compartmental models. example model compartment SEIR model split set spatial locations set age groups. crucial difficult assign meaningful consistent names compartments, flow rates, transmission rates, contact rates, sub-population sizes, parameters determining quantities. names convey different quantities relate one another. example, names make clear rate flow two compartments specific , say, age group location compartments. naming system facilitate identifying model quantities sets quantities. example, spatially structured model might want refer states particular location (e.g. Toronto) specific state within location (e.g. susceptible individuals Toronto). Model entities (e.g. states, flow rates, transmission rates), can described using data frame string-valued columns. rows data frames represent entities represented.  columns data frame represent different ways describe rows.   Non-empty values cell must contain letters, numbers, underscores, must start letter. Empty values zero-length strings can used indicate partitions applicable variables. purpose restrictions facilitate construction strings character vectors summarize different aspects data frame. taken together, summaries can inverted restore full labelled partition represent zero information loss. equivalence allows us go back--forth two representations without loosing information, perhaps gaining convenience. three types summaries: names, name, labels. names data frame names string-valued columns.   name data frame dot-concatenation names.   labels data frame row-wise dot-concatenation string-valued columns.   labels give unique single character string referring variable. labels one either names name, one may recover labelled partition. labels provide convenient names variables – .e. rownames. convention use UpperCamelCase partition names modified form snake_case variable labels. modification snake case allows single uppercase letters order accommodate convention epidemiology using single uppercase letters refer state variables. example, S, , R, well I_mild I_severe, consistent modified snake case style.","code":"EpiSympVax = data.frame(   Epi = c(rep(c(\"S\", \"E\", \"I\", \"I\", \"R\", \"beta\"), 2), \"alpha\", \"gamma\", \"gamma\", \"infectiousness\", \"infectiousness\", \"\"),   Symp = c(rep(c(\"\", \"\", \"mild\", \"severe\", \"\", \"\"), 2), \"\", \"mild\", \"severe\", \"mild\", \"severe\", \"\"),   Vax = c(rep(c(\"unvax\", \"vax\"), each = 6), \"\", \"\", \"\", \"\", \"\", \"dose_rate\") ) EpiSympVax #>               Epi   Symp       Vax #> 1               S            unvax #> 2               E            unvax #> 3               I   mild     unvax #> 4               I severe     unvax #> 5               R            unvax #> 6            beta            unvax #> 7               S              vax #> 8               E              vax #> 9               I   mild       vax #> 10              I severe       vax #> 11              R              vax #> 12           beta              vax #> 13          alpha #> 14          gamma   mild #> 15          gamma severe #> 16 infectiousness   mild #> 17 infectiousness severe #> 18                       dose_rate to_names(EpiSympVax) #> [1] \"Epi\"  \"Symp\" \"Vax\" to_name(EpiSympVax) #> [1] \"Epi.Symp.Vax\" to_labels(EpiSympVax) #>  [1] \"S..unvax\"               \"E..unvax\"               \"I.mild.unvax\" #>  [4] \"I.severe.unvax\"         \"R..unvax\"               \"beta..unvax\" #>  [7] \"S..vax\"                 \"E..vax\"                 \"I.mild.vax\" #> [10] \"I.severe.vax\"           \"R..vax\"                 \"beta..vax\" #> [13] \"alpha..\"                \"gamma.mild.\"            \"gamma.severe.\" #> [16] \"infectiousness.mild.\"   \"infectiousness.severe.\" \"..dose_rate\""},{"path":"https://canmod.github.io/macpan2/reference/nlist.html","id":null,"dir":"Reference","previous_headings":"","what":"Self Naming List — nlist","title":"Self Naming List — nlist","text":"Self Naming List","code":""},{"path":"https://canmod.github.io/macpan2/reference/nlist.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Self Naming List — nlist","text":"","code":"nlist(...)"},{"path":"https://canmod.github.io/macpan2/reference/nlist.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Self Naming List — nlist","text":"... Objects put list","code":""},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":null,"dir":"Reference","previous_headings":"","what":"Radial Basis Functions — rbf","title":"Radial Basis Functions — rbf","text":"Compute set radial basis functions (dimension ).","code":""},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Radial Basis Functions — rbf","text":"","code":"rbf(time_steps, dimension, scale = time_steps/dimension)"},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Radial Basis Functions — rbf","text":"time_steps number time steps model dimension number gaussians basis scale width gaussians","code":""},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Radial Basis Functions — rbf","text":"","code":"matplot(rbf(100, 5), type = \"l\")"},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":null,"dir":"Reference","previous_headings":"","what":"Print a table of contents of available models — show_models","title":"Print a table of contents of available models — show_models","text":"Collects information headers README files model directories returns results data frame","code":""},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Print a table of contents of available models — show_models","text":"","code":"show_models(   dir = system.file(\"starter_models\", package = \"macpan2\"),   show_missing = FALSE,   for_markdown = FALSE )"},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Print a table of contents of available models — show_models","text":"dir directory list show_missing (logical) include entries models README information? for_markdown (logical) format rendering table markdown-formatted links model readme files?","code":""},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Print a table of contents of available models — show_models","text":"data frame containing entries Directory (model directory), Title (model title), Description (short description)","code":""},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Print a table of contents of available models — show_models","text":"","code":"show_models(show_missing = TRUE) #>                       Directory                    Title #> 1                     awareness         Awareness Models #> 2                           hiv                      HIV #> 3    lotka_volterra_competition           Lotka-Volterra #> 4  lotka_volterra_predator_prey           Lotka-Volterra #> 5                   macpan_base              Macpan Base #> 6                          nfds  NFDS and Vaccine Design #> 7                          seir               Basic SEIR #> 8                        shiver    SHIVER = SEIR + H + V #> 9                            si                 Basic SI #> 10                          sir                Basic SIR #> 11                    sir_demog      SIR with Demography #> 12                 sir_mosquito     Mosquito-Vector  SIR #> 13                   sir_waning SIR with Waning Immunity #> 14                           ww         Wastewater Model #>                                                                                                        Description #> 1                                                                     Behaviour modifications in response to death #> 2                                                                                               A simple HIV model #> 3                                                                             Simple two-species competition model #> 4                                                                                       Simple predator-prey model #> 5                                                         Re-implementation of the McMaster group's COVID-19 model #> 6  An ecological model using population genomics to design optimal vaccines as implemented in Colijn et al. (2020) #> 7                                                                      Simple epidemic model with an exposed class #> 8                                                       A modified SEIR model with Hospitalization and Vaccination #> 9                                                                                     A very simple epidemic model #> 10                                                                                    A very simple epidemic model #> 11                                                                               An SIR model with birth and death #> 12                                                                                  SIR model for mosquito vectors #> 13                                                                  A basic SIR model with a flow from R back to S #> 14                                                             Macpan base with an additional wastewater component"},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":null,"dir":"Reference","previous_headings":"","what":"Simple Iterated Simulation — simple_sims","title":"Simple Iterated Simulation — simple_sims","text":"Simple Iterated Simulation","code":""},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simple Iterated Simulation — simple_sims","text":"","code":"simple_sims(iteration_exprs, time_steps, int_vecs = list(), mats = list())"},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simple Iterated Simulation — simple_sims","text":"iteration_exprs List expressions pass engine. expressions allowed use valid engine_functions. expression evaluated order, iteration. number iterations controlled time_steps argument. time_steps Number time steps iterate. int_vecs Named list integer vectors. mats Named list matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Simple Iterated Simulation — simple_sims","text":"data frame simulation results.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_positions.html","id":null,"dir":"Reference","previous_headings":"","what":"To Positions — to_positions","title":"To Positions — to_positions","text":"Return position vector indices corresponding input object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_positions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"To Positions — to_positions","text":"","code":"to_positions(x)"},{"path":"https://canmod.github.io/macpan2/reference/to_positions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"To Positions — to_positions","text":"x object class can converted position vector.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":null,"dir":"Reference","previous_headings":"","what":"To String — to_string","title":"To String — to_string","text":"Convert object string.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"To String — to_string","text":"","code":"to_string(x)"},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"To String — to_string","text":"x Object convert string.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"To String — to_string","text":"length-1 character vector.","code":""},{"path":"https://canmod.github.io/macpan2/reference/transform_distr_param.html","id":null,"dir":"Reference","previous_headings":"","what":"Distributional Parameter Transformation — transform_distr_param","title":"Distributional Parameter Transformation — transform_distr_param","text":"Objects used mp_identity - Identity transformation mp_log - Log transformation mp_logit - Logit transformation mp_sqrt - Square-root transformation","code":""},{"path":"https://canmod.github.io/macpan2/reference/transform_distr_param.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Distributional Parameter Transformation — transform_distr_param","text":"","code":"mp_identity  mp_log  mp_logit  mp_sqrt"},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-5-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.5.0 (news for this version is in-progress)","text":"Delete elements model specifications mp_tmb_delete.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-4-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.4.0 (news for this version is in-progress)","text":"Repeated calls optimizer now start previous best parameter vector longer fit full covariance matrix sdreports","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"bug-fixes-1-4-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"macpan2 1.4.0 (news for this version is in-progress)","text":"Row vectors names longer break spec print methods","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-3-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.3.0","text":"longer exporting nlist. Removing -place modifications model specification objects mp_tmb_insert mp_tmb_update.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-3-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.3.0","text":"Define explicit state variable updates, choice applying mp_euler, mp_rk4, mp_euler_multinomial update methods, latter generating process error. New stochasticity engine functions rbinom reulermultinom. mp_tmb_fixef_cov function getting covariance matrix fixed effects. mp_trajectory_ensemble mp_trajectory_sim functions summarizing random variation trajectories. Unpacking assignment engine. means can things like c(x, y) ~ z, values z assigned elements x, y, etc… row-major order. to_name_pairs function returning pairwise dot-concatenations elements character vector without dots. to_values function extracting column data frame single numerical column turning numeric matrices arrays dimnames flattened numeric vector labels produced appropriately dot-concatenating dimnames.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"bug-fixes-1-3-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"macpan2 1.3.0","text":"Several bugs related input handling mp_tmb_calibrator (#176)","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"doc-fixes-and-updates-1-3-0","dir":"Changelog","previous_headings":"","what":"Doc Fixes and Updates","title":"macpan2 1.3.0","text":"New installation instructions installing r-universe. New vignette: real_data. Document to_name, to_names, to_labels, handle naming structured objects. Document print function ?engine_functions. simple_sims example ?engine_functions now runs without error. Help file examples mp_tmb_insert mp_tmb_update. Readme/vignette examples better expose calls library user.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-1-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.1.0","text":"simple_sims longer returns outputs zeroth time-step. Using last.par.best finalize TMB objective function following optimization. group_sums now checks bad group indexes. rbind_lag now throws error lag > 1 conceptual errors case. get back can allow important cases adding argument initial conditions associated negative time steps.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-1-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.1.0","text":"Streamlined installation via r-universe. mp_tmb_calibrator mp_tmb_optimize functions calibration using simple restrictive trajectory matching model. Future releases allow functionality. mp_tmb_coef mp_tmbstan_coef tables statistical parameters used calibration. mp_trajectory_sd mp_trajectory_ensemble getting information fitted trajectory uncertainty. mp_tmb_update|insert functions creating new model specs existing ones. Parameters specified data frame can now place default values columns following names: \"default\", \"Default\", \"value\", \"Value\", \"val\", \"Val\" mp_tmb_library can return list model specs alternative_specs, model makes alternatives available. time_var engine function better old time_group, required two expressions rather one thing. time_group remain softly deprecated. Fixed effects extractor formatter. mp_default function extracting spec simulator defaults long-format. rbind_time allows integer vectors subsetting times options(macpan2_verbose = FALSE) turn flood information provided TMB. Note takes effect set creating TMB simulator.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"bug-fixes-1-1-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"macpan2 1.1.0","text":"Segfaults --range assignment.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"doc-fixes-and-updates-1-1-0","dir":"Changelog","previous_headings":"","what":"Doc Fixes and Updates","title":"macpan2 1.1.0","text":"(progress) Calibration vignette updated simpler quick-start, previous advanced material moved advanced vignette. mp_tmb_model_spec documentation filled . group_sums TMB engine function third argument updated old pre-1.0.0 behaviour.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-0-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.0.0","text":"flows.csv, derivations.json files library, instead tmb.R files. Compartmental function, instead mp_tmb_model_spec mp_tmb_library. {group|row|col}Sums now called {group|row|col}_sums. Final argument group_sums used length output vector, now vector desired output length. TMBModel associated classes (ExprList) longer exported, favour mp_... functions similar things. Sort simulation output time step.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-0-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.0.0","text":"Constant integer vectors can now passed C++. Integer vectors can used subset assignment matrices (.e. integer subsetting left-hand-side). mp_trajectory() function, roughly equivalent model$report(..., .phases = \"\"). New print function TMB engine. need declare empty matrices creating TMB model objects, matrices derived automatically detected.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"experimental-features-1-0-0","dir":"Changelog","previous_headings":"","what":"Experimental Features","title":"macpan2 1.0.0","text":"Model structure grammar (mp_index(), mp_join(), etc.) Log files","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"macpan2-003","dir":"Changelog","previous_headings":"","what":"macpan2 0.0.3","title":"macpan2 0.0.3","text":"Optimize C++ simulation history storage avoiding unnecessary allocations Use state flow names expression inserters Chattier validity checking Radial basis functions macpan-base – re-implementation McMaster group’s COVID-19 model macpan2 ww – wastewater model (doesn’t yet readme) new readme clean previous models Report expression broke C++ side Developer tools switching different C++ files working directories Package reference organization cleanup (thanks @bbolker ) Time-varying parameters vignette","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"macpan2-002","dir":"Changelog","previous_headings":"","what":"macpan2 0.0.2","title":"macpan2 0.0.2","text":"Interface optimization TMB simulation objects TMB simulation model updating caching Parameter transformations Get initial values matrices TMB simulation objects State flow variable names can used expressions contexts Example model indexing (thank @bbolker!) Engine function rbind_time defaults row binding full simulation history Fix bug entire model inflows outflows Fix bugs symbolic R-side manipulation expressions Fix previously broken argument_dots option model definition files (thank @Flynn-Primrose )","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"macpan2-001","dir":"Changelog","previous_headings":"","what":"macpan2 0.0.1","title":"macpan2 0.0.1","text":"Initial release.","code":""}]
+[{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":null,"dir":"","previous_headings":"","what":"Contributing to macpan2","title":"Contributing to macpan2","text":"Thank contributing macpan2. Pull requests issues welcome! Developers can see documentation useful contribute code.","code":""},{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":"developer-installation","dir":"","previous_headings":"","what":"Developer Installation","title":"Contributing to macpan2","text":"Developers contributors clone repository call make command-line top level directory. following make rules available getting control build process.","code":"make quick-install     # for changes that only modify R source make quick-doc-install # for changes that modify R source and roxygen comments make quick-test        # quick-doc-install + run-examples + run-tests make run-examples      # help file checks only (without package rebuild) make run-tests         # run scripts in tests (without package rebuild) make full-install      # for all changes, including changes to C++ source make src-update        # push changes to dev.cpp to macpan2.cpp (see below) make enum-update       # register new C++ engine functions on the R-side make engine-doc-update # generate roxygen comments from comments in dev.cpp make doc-update        # roxygenize make pkg-build         # build the R package make pkg-install       # install the R package from the build make pkg-check         # R package checks"},{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":"c-development","dir":"","previous_headings":"","what":"C++ Development","title":"Contributing to macpan2","text":"R packages compiled code, developers edit source files compiled src directory. macpan2 single file directory called macpan2, generated automatically file misc/dev/dev.cpp. setup allows quicker C++ development cycles, developers can edit misc/dev/dev.cpp use file tests without needing re-install package new source. particular, hello-world example use dev.cpp follows. update src/macpan2 state misc/dev/dev.cpp one may run make src-update. Running misc/dev/dev.cpp print debugging information verbose manner, whereas src/macpan2.cpp . src-update make rule removes #define MP_VERBOSE flag top file.","code":"library(macpan2) macpan2:::dev_compile() ## compile dev.cpp options(macpan2_dll = \"dev\") sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") mp_simulator(sir, time_steps = 100, outputs = \"I\")"},{"path":"https://canmod.github.io/macpan2/CONTRIBUTING.html","id":"make-in-windows","dir":"","previous_headings":"","what":"Make in Windows","title":"Contributing to macpan2","text":"Developers using make Windows, encounter following compilation error. resolve , may need pass -Wa,-mbig-obj compiler flag GCC via Makeconf file located R installation directory (typically C/Program Files/R/[version R]/etc/x64). Locate CXXFLAGS macro Makeconf file. look something like following. CXXFLAGS = -O2 -Wall $(DEBUGFLAG) -mfpmath=sse -msse2 -mstackrealign $(LTO) Append -Wa,-mbig-obj flag end line save file. likely need make change using Windows Administrator role. CXXFLAGS = -O2 -Wall $(DEBUGFLAG) -mfpmath=sse -msse2 -mstackrealign $(LTO) -Wa,-mbig-obj now able use make described. Note change might increase compilation time (~2 min) described . nice able set flag globally Windows developers. attempt made update Makefile additional line, CXXFLAGS := $(CXXFLAGS) -Wa,-mbig-obj, suggested , successful.","code":"Fatal error: can't write xxx bytes to section .text of macpan2.o: 'file too big' as: macpan2.o: too many sections"},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"setup-and-example-models-and-data","dir":"Articles","previous_headings":"","what":"Setup and Example Models and Data","title":"FAQs","text":"","code":"library(macpan2) library(ggplot2) library(dplyr) library(broom.mixed) options(macpan2_verbose =  FALSE) library(macpan2) si = mp_tmb_model_spec(     before = S ~ 1 - I   , during = mp_per_capita_flow(         from     = \"S\"         ## compartment from which individuals flow       , to       = \"I\"         ## compartment to which individuals flow       , rate     = \"beta * I\"  ## expression giving _per-capita_ flow rate       , abs_rate = \"infection\" ## name for _absolute_ flow rate = beta * I * S     )   , default = list(I = 0.01, beta = 0.2) ) print(si) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       I          0.01 #>    beta          0.20 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ 1 - I #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I\", abs_rate = \"infection\") library(ggplot2) library(dplyr) example_data = (si  |> mp_simulator(time_steps = 50, outputs = \"infection\")  |> mp_trajectory() ) incidence_example = (example_data  |> mutate(value = 100 * value)  |> pull(value) )"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-is-the-package-called-macpan2","dir":"Articles","previous_headings":"Naming Convensions","what":"Why is the package called macpan2?","title":"FAQs","text":"macpan2 package grew McMasterPandemic project. years people involved project started calling macpan, macpan2 successor. package called macpan.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-do-most-of-the-functions-start-with-mp_","dir":"Articles","previous_headings":"Naming Convensions","what":"Why do most of the functions start with mp_?","title":"FAQs","text":"mp stands mac-pan. idea make easy see scripts functions come macpan2 functions come packages.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-do-some-of-the-functions-start-with-mp_tmb_","dir":"Articles","previous_headings":"Naming Convensions","what":"Why do some of the functions start with mp_tmb_?","title":"FAQs","text":"tmb part refers TMB package, macpan2 built. hope one day use computational engines (e.g., stan), point users able see computational engine used scripts. now tmb computational engine thing indicated mp_tmb_ using function intended specific computations TMB. Functions start mp_tmb_ engine-agnostic able used engine engines supported.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-does-mean","dir":"Articles","previous_headings":"Coding Style","what":"What does |> mean?","title":"FAQs","text":"use base R pipe operator throughout examples. Please read link details.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"why-do-i-see-weird-symbols-at-the-start-of-lines","dir":"Articles","previous_headings":"Coding Style","what":"Why do I see weird symbols at the start of lines?","title":"FAQs","text":"many examples start lines characters many people put end lines, commas, plus signs base R pipe. characters tell R code rest line combined previous lines. prefer put characters start lines makes slightly easier comment lines . Note approach work need wrap continued expressions parentheses. See quickstart guide examples style.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-model-fitting-approach-does-macpan2-use","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"What model fitting approach does macpan2 use?","title":"FAQs","text":"fit models finding values parameters peak posterior distribution. approach sometimes called maximum posteriori (MAP) estimation. approach allows us get approximate Bayesian uncertainty estimates approximating posterior distribution multivariate Gaussian centered peak obtained MAP. One able declare parameters considered random effects, means integrated posterior distribution using Laplace approximation. Using approach allows us reduce dimensionality posterior distribution used MAP optimizing fixed effect parameters. approximate posterior distribution can used obtain confidence / credible intervals continuous function model variables. two main examples follows. Confidence intervals fitted parameters using mp_tmb_coef(., conf.int = TRUE). Confidence intervals fitted trajectories using mp_trajectory_sd() approach computing confidence intervals using Gaussian approximations posterior special case delta method implemented TMB, described . Example calibrations varying levels complexity. Intro calibration using toy data Intro calibration using real scarlet fever data hackers McMaster COVID model Wastewater model COVID SHIVER model COVID SEIR model using toy data","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-likelihood-and-prior-distribution-assumptions-does-macpan2-make","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"What likelihood and prior distribution assumptions does macpan2 make?","title":"FAQs","text":"free declare value model trajectory parameter. Trajectories compared observed data produce likelihood component (e.g., case reports distributed negative binomial distribution dispersion parameter 1) parameters used produce component prior distribution (e.g., transmission rate log normally distributed mean 0.2 standard deviation 1). Available distributional assumptions settings described , inspecting examples linked previous FAQ useful figuring use functionality.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-i-hack-macpan2-to-use-mcmc-esimation","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"Can I hack macpan2 to use MCMC esimation?","title":"FAQs","text":"Yes.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-i-get-a-new-model-specification-with-fitted-parameters-as-defaults-from-a-calibrated-calibrator-object","dir":"Articles","previous_headings":"Calibration Details and Outputs","what":"Can I get a new model specification with fitted parameters as defaults, from a calibrated calibrator object?","title":"FAQs","text":"Coming soon!","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-can-i-plot-simulated-trajectories","dir":"Articles","previous_headings":"Plotting Simulated Trajectories","what":"How can I plot simulated trajectories?","title":"FAQs","text":"question answered quickstart guide.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-can-i-plot-a-calibrated-model-with-the-observed-data-used-in-the-calibration","dir":"Articles","previous_headings":"Plotting Simulated Trajectories","what":"How can I plot a calibrated model with the observed data used in the calibration?","title":"FAQs","text":"favourite way .","code":"fitted_data = mp_trajectory(model_calibrator) (observed_data   |> ggplot()   + geom_point(aes(time, value))   + geom_line(aes(time, value), data = fitted_data)   + theme_bw() )"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"should-i-worry-about-nanan-function-evaluation-warnings","dir":"Articles","previous_headings":"Calibration Troubleshooting","what":"Should I worry about NA/NaN function evaluation warnings?","title":"FAQs","text":"optimizer sometimes give warnings like . usually nothing worry , though take note . Typically warning indicates optimizer tried parameter values led objective function (.e., negative log posterior density) non-numeric. Usually, opimizer smart enough (possible) get back track. key thing watch whether optimizer converged, can explored using mp_optimizer_output() function illustrated article.","code":"Warning messages: 1: In (function (start, objective, gradient = NULL, hessian = NULL,  :   NA/NaN function evaluation"},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-should-i-do-if-i-do-not-converge","dir":"Articles","previous_headings":"Calibration Troubleshooting","what":"What should I do if I do not converge?","title":"FAQs","text":"depends reason non-convergence. optimizer tries give information , can get information using mp_optimizer_output().","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-do-i-increase-the-number-of-iterations-that-the-optimizer-takes","dir":"Articles","previous_headings":"Calibration Troubleshooting","what":"How do I increase the number of iterations that the optimizer takes?","title":"FAQs","text":"non-convergence results optimizer reaches maximum number iterations allowed take, can increase number (TODO: show example ). Sometimes however, running iterations can (always) sign much information data model parameters estimated.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-can-i-do-when-my-confidence-intervals-overlap-zero-for-a-parameter-that-should-be-positive","dir":"Articles","previous_headings":"Parameter Estimation and Uncertainty","what":"What can I do when my confidence intervals overlap zero for a parameter that should be positive?","title":"FAQs","text":"use mp_tmb_insert() transform parameters go negative. TODO: link example.","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-i-weight-the-importance-of-trajectories-when-fitting-to-more-than-one-of-them","dir":"Articles","previous_headings":"Parameter Estimation and Uncertainty","what":"Can I weight the importance of trajectories when fitting to more than one of them?","title":"FAQs","text":"Yes, recommended deep . TODO: give explanation link example.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-is-the-best-way-for-me-to-keep-my-state-variables-from-going-negative","dir":"Articles","previous_headings":"Dynamical Instabilities","what":"What is the best way for me to keep my state variables from going negative?","title":"FAQs","text":"hazard correction (mp_hazard()) works best experience. TODO: link example.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"my-data-start-mid-epidemic-so-how-do-i-know-what-the-initial-number-of-infectious-individuals-is","dir":"Articles","previous_headings":"Initial Conditions","what":"My data start mid-epidemic so how do I know what the initial number of infectious individuals is?","title":"FAQs","text":"common situation data collection often gets better clear problem. simulating epidemic models requires specifying initial conditions state variables, data . basic idea solving problem fit initial numbers state variables. issues. Let’s get example. manipulate example infection data removing first 25 time steps. first issue set time steps . just keep (.e., 26:50) cheating preserving time start epidemic 25 time steps , real life know information. pretend epidemic started 10 time steps data start.  blank space graph time 1 10 represents period outbreak without data. exact size period crucial, long enough let dynamics model settle become independent initial values state variables. Actually, simple SI model example even ignore start-time issue, just fit initial values number infectious individuals. models many state variables becomes easy specify initial conditions model wouldn’t go naturally, resulting dynamical instability. instability can cause optimization problems optimizer might choose starting conditions lead instabilities therefore bad fits. continue SI model illustrate general idea relative simplicity. key ideas code . express initial number infectious individuals N times logistic function new parameter, logit_prop_I, giving proportion population infectious logit scale. transformation allows us fit logit_prop_I ensuring initial value stays 0 N. use mp_sim_bounds function assert first time step 1 last time step max_time, case 35. give prior distribution logit_prop_I see able fit transmission rate, beta, initial proportion infectious individuals, get reasonable confidence intervals. Note logit_prop_I automatically back-transformed prop_I, functionality can turned setting back_transform = FALSE mp_tmb_coef. plot shows model able fit data without knowing initial number infectious individuals 10  Real data simple, principles help.","code":"start_date_offset = 10 in_progress_epidemic = (example_data   |> filter(time > 25)   |> mutate(         value = rpois(length(value), 100 * value)       , time = start_date_offset + row_number()   ) ) max_time = max(in_progress_epidemic$time) (ggplot()   + geom_point(aes(time, value), data = in_progress_epidemic)   + scale_x_continuous(limits = c(1, max_time))   + theme_bw() ) calibrator = (\"starter_models\"  |> mp_tmb_library(\"si\", package = \"macpan2\")  |> mp_tmb_insert(phase = \"before\"     , expressions = list(I ~ N / (1 + exp(-logit_prop_I)))     , default = list(logit_prop_I = 0)   )  |> mp_tmb_calibrator(       data = in_progress_epidemic     , traj = list(infection = mp_neg_bin(disp = 1))     , par = list(         beta = mp_normal(location = 0.4, sd = 1)       , logit_prop_I = mp_normal(location = 0, sd = 1)     )     , time = mp_sim_bounds(1, max_time, \"steps\")  ) ) mp_optimize(calibrator) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>     params     params  #> 0.09910844 0.55847313  #>  #> $objective #> [1] 38.00748 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 9 #>  #> $evaluations #> function gradient  #>       14       10  #>  #> $message #> [1] \"relative convergence (4)\" cc = mp_tmb_coef(calibrator, conf.int = TRUE) print(cc) #>       term    mat row col default  type   estimate  std.error   conf.low #> 1   params   beta   0   0     0.2 fixed 0.09910844 0.04234644 0.01611094 #> 2 params.1 prop_I   0   0     0.5 fixed 0.63609918 0.42942417 0.04404283 #>   conf.high #> 1 0.1821059 #> 2 0.9851457 fitted_data = mp_trajectory(calibrator) (ggplot()   + geom_point(aes(time, value), data = in_progress_epidemic)   + geom_line(aes(time, value), data = fitted_data)   + theme_bw() )"},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"how-should-i-account-for-delayed-reporting-as-well-as-under-reporting-in-macpan2","dir":"Articles","previous_headings":"Under Reporting, Delayed Reporting, and Total Reporting","what":"How should I account for delayed reporting as well as under-reporting in macpan2?","title":"FAQs","text":"challenge introduced reporting delays compare simulated incidence values model observed case reports, reporting delay. following toy example shows apparent peak data follows simulations.  comparing simulations observed data, use convolution transform simulated incidence values time series reported cases expected model. Keep reading find specifically done.  Now can now compare observed expected reported cases manner accounts reporting delays.  Now explain expected reported case curve computed. method assume new case waits Gamma-distributed random amount time observed. mean coefficient variation distribution can fitted parameters. COVID-19 pandemic McMaster group found Gamma distribution mean delay 11 days coefficient variation 0.25 reasonable model. following figure illustrates single expected case report computed, case time 26. Gamma distribution delay times represented bars giving probability new case particular time reported time 26, given dashed horizontal line. Note reported number cases roughly near (identical) simulated number cases peak delay distribution. makes sense expect reports now come highest probability time past.  macpan2 typically model doesn’t account delayed reporting want update fitting data. One can use mp_tmb_insert_reports() function purpose.  Note function allows accounting -reporting well, specifying report_prob less 1.","code":"si_with_delays = (si  |> mp_tmb_insert_reports(       incidence_name = \"infection\"     , mean_delay = 11     , cv_delay = 0.25     , report_prob = 0.1     , reports_name = \"reports\"  ) ) (si_with_delays   |> mp_simulator(       time_steps = 50L     , outputs = c(\"infection\", \"reports\")   )   |> mp_trajectory()   |> ggplot()   + geom_line(aes(time, value, colour = matrix))   + theme_bw() ) 16: dist ~ pgamma(1:17, 1/(incidence_cv_delay), incidence_mean_delay * (incidence_cv_delay^2)) 17: delta ~ dist[1:16] - dist[0:15] 18: kernel ~ incidence_report_prob * delta/sum(delta) 19: reported_incidence ~ convolution(incidence, kernel)"},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"what-are-the-mathematical-details-of-the-euler-multinomial-process-error-model","dir":"Articles","previous_headings":"Stochastic Simulation","what":"What are the mathematical details of the Euler multinomial process error model?","title":"FAQs","text":"Euler-multinomial state update method assumes number individuals move one box another single time-step random non-negative integer, coming particular multinomial distribution now describe. probability staying iith box entire time-step assumed following (TODO: relate Poisson processes). pii=exp(−∑jrij) p_{ii} = \\exp\\left(-\\sum_j r_{ij}\\right) probability assumes rijr_{ij} held constant throughout entire time-step, although can change time-step begins. probability moving box ii box jj one time-step given following. pij=(1−pii)rij∑jrij p_{ij} = (1 - p_{ii}) \\frac{r_{ij}}{\\sum_j r_{ij}} probability just probability staying box ii, 1−pii1 - p_{ii}, specifically going box jj, assumed given expression rij∑jrij\\frac{r_{ij}}{\\sum_j r_{ij}}. Let ρij\\rho_{ij} random number individuals move box ii box jj one time-step. expected value ρij\\rho_{ij} pijxip_{ij} x_i. However, random variables independent events, total number individuals, ∑ixi\\sum_i x_i, remain constant single time-step (least models currently considering). account non-independence, collect ρij\\rho_{ij} associated compartment ii vector ρi\\rho_i. collect similar vector probabilities, pip_i. ρi\\rho_i random draw multinomial distribution xix_i trials probability vector, pip_i. random draws made, state variables can updated time-step follows. xi=xi−∑jρij+∑jρji x_i = x_i - \\sum_j \\rho_{ij} + \\sum_j \\rho_{ji} Note actually need generate values diagonal elements, ρii\\rho_{ii}, cancel update equation. also can ignore ρij\\rho_{ij} rij=0r_{ij} = 0. SIR example particularly simple Euler-binomial distribution branching flows – individuals leave S can go leave can go R. two flows given following distributions. ρSI∼Binomial(S,pSI) \\rho_{SI} \\sim \\text{Binomial}(S, p_{SI}) ρIR∼Binomial(,pIR) \\rho_{IR} \\sim \\text{Binomial}(, p_{IR}) models branching flows multinomial distributions. model state update given following equations. S=S−ρSI S = S - \\rho_{SI} =−ρIR+ρSI = - \\rho_{IR} + \\rho_{SI} R=R+ρIR R = R + \\rho_{IR}","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"can-macpan2-do-the-gillespie-algorithm","dir":"Articles","previous_headings":"Stochastic Simulation","what":"Can macpan2 do the Gillespie algorithm","title":"FAQs","text":". least without substantial hacking. Euler Multinomial used instead","code":""},{"path":"https://canmod.github.io/macpan2/articles/FAQs.html","id":"more-process-error-incomplete","dir":"Articles","previous_headings":"Stochastic Simulation","what":"More Process Error (incomplete)","title":"FAQs","text":"","code":"set.seed(1L) spec = mp_tmb_model_spec(     before = list(         R ~ vaxprop * N       , S ~ N - I - R     )   , during = list(         infection ~ reulermultinom(S, beta * I / N)       , recovery ~ reulermultinom(I, gamma)       , S ~ S - infection       , I ~ I + infection - recovery       , R ~ R + recovery     )   , default = list(         vaxprop = 0.71111111       , N = 1000       , I = 10       , beta = 1.25       , gamma = 1.1     ) ) (spec   |> mp_simulator(       time_steps = 10     , outputs = \"infection\"   )    |> mp_trajectory_replicate(1L) ) #> [[1]] #>       matrix time row col value #> 1  infection    1   0   0     2 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     1 #> 4  infection    4   0   0     3 #> 5  infection    5   0   0     2 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 vaxprop = 0.7 N = 1000 set.seed(10) spec = mp_tmb_model_spec(     before = list(S ~ N - I - R)   , during = list(         infection ~ reulermultinom(S, beta * I / N)       , recovery ~ reulermultinom(I, gamma)       , S ~ S - infection       , I ~ I + infection - recovery       , R ~ R + recovery     )   , default = list(         N = N       , R = round(vaxprop * N)       , I = 10       , beta = 1.25       , gamma = 1.1     ) ) sim = (spec   |> mp_simulator(       time_steps = 10     , outputs = \"infection\"   ) ) sim |> mp_trajectory_replicate(10) #> [[1]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[2]] #>       matrix time row col value #> 1  infection    1   0   0     4 #> 2  infection    2   0   0     3 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[3]] #>       matrix time row col value #> 1  infection    1   0   0     1 #> 2  infection    2   0   0     1 #> 3  infection    3   0   0     2 #> 4  infection    4   0   0     2 #> 5  infection    5   0   0     1 #> 6  infection    6   0   0     1 #> 7  infection    7   0   0     1 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[4]] #>       matrix time row col value #> 1  infection    1   0   0     2 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     3 #> 4  infection    4   0   0     3 #> 5  infection    5   0   0     1 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[5]] #>       matrix time row col value #> 1  infection    1   0   0     0 #> 2  infection    2   0   0     0 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[6]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[7]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     4 #> 3  infection    3   0   0     3 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[8]] #>       matrix time row col value #> 1  infection    1   0   0     4 #> 2  infection    2   0   0     0 #> 3  infection    3   0   0     0 #> 4  infection    4   0   0     0 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[9]] #>       matrix time row col value #> 1  infection    1   0   0     6 #> 2  infection    2   0   0     2 #> 3  infection    3   0   0     1 #> 4  infection    4   0   0     1 #> 5  infection    5   0   0     0 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 #>  #> [[10]] #>       matrix time row col value #> 1  infection    1   0   0     3 #> 2  infection    2   0   0     3 #> 3  infection    3   0   0     1 #> 4  infection    4   0   0     1 #> 5  infection    5   0   0     1 #> 6  infection    6   0   0     0 #> 7  infection    7   0   0     0 #> 8  infection    8   0   0     0 #> 9  infection    9   0   0     0 #> 10 infection   10   0   0     0 proc_err = rnorm(50) spec = mp_tmb_model_spec(     before = list(S ~ N - I - R)   , during = list(         mean_foi ~ beta * I / N       , mean_infection ~ mean_foi * S       , dev_foi ~ exp(proc_err[time_step(1)])       , mp_per_capita_flow(\"S\", \"I\", \"dev_foi * mean_foi\", \"infection\")       , mp_per_capita_flow(\"I\", \"R\", \"gamma\", \"recovery\")     )   , default = list(         N = N       , R = 0       , I = 1       , beta = 0.4       , gamma = 0.2       , proc_err = proc_err     ) ) sim = (spec |> mp_hazard()   |> mp_simulator(       time_steps = 50     , outputs = \"infection\"   ) ) sim_infection = (sim   |> mp_trajectory()   |> mutate(value = rpois(length(value), value)) ) fixef = list(     beta = mp_log_normal(location = 0.2, sd = 1)   , gamma = mp_log_normal(location = 0.2, sd = 1) ) ranef = list()   #proc_err = mp_normal(location = 0, sd = 0.1) #) cal = mp_tmb_calibrator(     spec = mp_tmb_update(spec, default = list(beta = 0.2, proc_err = rep(0, 50)))   , data = sim_infection   , traj = list(infection = mp_neg_bin(disp = 1))   , par = fixef # mp_par(param = fixef, random = ranef)   , outputs = \"mean_infection\" ) mp_optimize(cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>    params    params  #> 0.5811725 0.2381576  #>  #> $objective #> [1] 215.4921 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 10 #>  #> $evaluations #> function gradient  #>       13       11  #>  #> $message #> [1] \"relative convergence (4)\" mp_tmb_coef(cal) #>       term   mat row col default  type  estimate  std.error #> 1   params  beta   0   0     0.2 fixed 0.5811725 0.03470795 #> 2 params.1 gamma   0   0     0.2 fixed 0.2381576 0.04467113 fit_infection = mp_trajectory(cal) (ggplot()   + geom_point(aes(time, value), data = sim_infection)   + geom_line(aes(time, value, colour = matrix), data = fit_infection)   + theme_bw() )"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"hello-world","dir":"Articles","previous_headings":"","what":"Hello World","title":"Calibrating Compartmental Models to Data","text":"’ll first thing always trying new fitting procedure: simulate clean, nice data model see can recover something close true parameters.","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-0-set-up-simulator-and-generate-data","dir":"Articles","previous_headings":"Hello World","what":"Step 0: set up simulator and generate ‘data’","title":"Calibrating Compartmental Models to Data","text":"using several different versions SIR model, can derived SIR specification model library. specification derive first version model, use generate synthetic data see optimization can recover parameters use simulating.  Note changed default values can try recover using optimization . make things little challenging add Poisson noise prevalence () value:","code":"sir_spec = mp_tmb_library(\"starter_models\"   , \"sir\"   , package = \"macpan2\" ) print(sir_spec) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 300, R = 100, beta = 0.25, gamma = 0.1) ) sir_results = mp_trajectory(sir_simulator) (sir_results   |> ggplot(aes(time, value, colour = matrix))   + geom_line() ) set.seed(101) sir_prevalence = (sir_results     |> dplyr::select(-c(row, col))     |> filter(matrix == \"I\")     |> rename(true_value = value)     |> mutate(value = rpois(n(), true_value)) ) plot_truth <- ggplot(sir_prevalence, aes(time)) +     geom_point(aes(y = value)) +     geom_line(aes(y = true_value)) print(plot_truth)"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-1-add-calibration-information","dir":"Articles","previous_headings":"Hello World","what":"Step 1: add calibration information","title":"Calibrating Compartmental Models to Data","text":"next step produce object can calibrated optimization. make model need specify trajectory fit (case). also need specify parameters fit. value default list model spec can selected fitting. Note change default value N, leave parameters model spec. difference defaults simulator versus calibrator hope recover using optimization. Note calibrator new expressions deal comparisons data. particular objective function optimize. can sanity check make sure default values give reasonable-looking trajectory.","code":"sir_calibrator = mp_tmb_calibrator(sir_spec   , data = sir_prevalence   , traj = \"I\"   , par = c(\"beta\", \"R\")   , default = list(N = 300) ) print(sir_calibrator) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ S * (I * beta/N) #> 2: recovery ~ I * (gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>  #> --------------------- #> After the simulation loop (t = T + 1): #> --------------------- #> 1: sim_I ~ rbind_time(I, obs_times_I) #>  #> --------------------- #> Objective function: #> --------------------- #> ~-sum(dpois(obs_I, clamp(sim_I))) (sir_calibrator   |> mp_trajectory()  |> ggplot(aes(time, value))   + geom_line() )"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-2-do-the-fit","dir":"Articles","previous_headings":"Hello World","what":"Step 2: do the fit","title":"Calibrating Compartmental Models to Data","text":"fit straightforward. Note mp_optimize function modified sir_calibrator object, now contains new fitted parameter values results optimization.","code":"mp_optimize(sir_calibrator)"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"step-3-check-the-fit","dir":"Articles","previous_headings":"Hello World","what":"Step 3: check the fit","title":"Calibrating Compartmental Models to Data","text":"can print results optimizer (nlminb case) using mp_optimizer_output function. Always check value convergence code (’s 0, something may gone wrong …). mentioned , best-fit parameters stored internally, can get information using mp_tmb_coef function. (Note get message broom.mixed package, please install . mp_tmb_coef wrapper function). correspond pretty well known true values simulation model. known simulated true value trajectory (black line) fact fall within 95% confidence region (red ribbon).","code":"mp_optimizer_output(sir_calibrator) #> $par #>     params     params  #>  0.2345619 86.7030872  #>  #> $objective #> [1] 248.5816 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 12 #>  #> $evaluations #> function gradient  #>       22       12  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" mp_optimize(sir_calibrator) #> $par #>     params     params  #>  0.2345619 86.7030872  #>  #> $objective #> [1] 248.5816 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 1 #>  #> $evaluations #> function gradient  #>        2        1  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" mp_optimizer_output(sir_calibrator, what=\"all\") #> [[1]] #> [[1]]$par #>     params     params  #>  0.2345619 86.7030872  #>  #> [[1]]$objective #> [1] 248.5816 #>  #> [[1]]$convergence #> [1] 0 #>  #> [[1]]$iterations #> [1] 12 #>  #> [[1]]$evaluations #> function gradient  #>       22       12  #>  #> [[1]]$message #> [1] \"both X-convergence and relative convergence (5)\" #>  #>  #> [[2]] #> [[2]]$par #>     params     params  #>  0.2345619 86.7030872  #>  #> [[2]]$objective #> [1] 248.5816 #>  #> [[2]]$convergence #> [1] 0 #>  #> [[2]]$iterations #> [1] 1 #>  #> [[2]]$evaluations #> function gradient  #>        2        1  #>  #> [[2]]$message #> [1] \"both X-convergence and relative convergence (5)\" sir_estimates = mp_tmb_coef(sir_calibrator, conf.int = TRUE) print(sir_estimates) #>       term  mat row col default  type   estimate   std.error   conf.low #> 1   params beta   0   0     0.2 fixed  0.2345619 0.008739338  0.2174331 #> 2 params.1    R   0   0     0.0 fixed 86.7030872 7.028753743 72.9269830 #>     conf.high #> 1   0.2516906 #> 2 100.4791914 mp_default(sir_simulator) |> filter(matrix %in% sir_estimates$mat) #>   matrix row col  value #> 1      R         100.00 #> 2   beta           0.25 sim_vals <- (sir_calibrator   |> mp_trajectory_sd(conf.int = TRUE)   |> filter(matrix == \"I\") ) (plot_truth    + geom_line(data = sim_vals     , aes(y = value)     , colour = \"red\"   )   + geom_ribbon(data = sim_vals     , aes(ymin = conf.low, ymax = conf.high)     , fill = \"red\"     , alpha = 0.2   ) )"},{"path":"https://canmod.github.io/macpan2/articles/calibration.html","id":"statistical-model","dir":"Articles","previous_headings":"","what":"Statistical Model","title":"Calibrating Compartmental Models to Data","text":"specific statistical model used fit data. describe . Let observed simulated trajectories vectors IobsI_\\textrm{obs} IsimI_\\textrm{sim}. II symbol chosen fitted prevalence , trajectory model. example, traj = \"infection\" fitted incidence, infection variable model number new cases every time step. simulated trajectories actually function vector, 𝐛\\mathbf b, default values chose make statistical parameters. Therefore, write simulated trajectory function, Isim(𝐛)I_\\textrm{sim}(\\mathbf b). assume observed trajectory Poisson distributed mean given simulated trajectory. Iobs∼Poisson(Isim(𝐛)) I_{\\textrm{obs}} \\sim \\textrm{Poisson}(I_\\textrm{sim}(\\mathbf b)) Given assumptions choose 𝐛\\mathbf b maximize resulting likelihood function, use functionality TMB package (sometimes tmbstan/rstan packages) statistical inference fitted parameters trajectories. recognize statistical model often overly restrictive. macpan2 package developer interface much flexible, allowing detailed control TMB, tmbstan, rstan. interface allows arbitrary likelihood functions, prior distributions, parameter transformations, flexible parameter time-variation models, random effects . See information, although guides describe developer interface instructions may unclear many readers. plan continue adding interface layers, interface described vignette, macpan2 can exposed users.","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"hello-world-an-easy-calibration-exercise","dir":"Articles","previous_headings":"","what":"‘Hello, World’: an easy (??) calibration exercise","title":"Advanced Calibration","text":"’ll first thing always trying new fitting procedure: simulate clean, nice data model see can recover something close true parameters.","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-0-set-up-simulator-and-generate-data","dir":"Articles","previous_headings":"‘Hello, World’: an easy (??) calibration exercise","what":"Step 0: set up simulator and generate ‘data’","title":"Advanced Calibration","text":"using several different versions SIR model, can derived SIR specification model library. specification derive first version model, use generate synthetic data see optimization can recover parameters use simulating. Add noise prevalence () value:","code":"sir_spec = mp_tmb_library(\"starter_models\"   , \"sir\"   , package = \"macpan2\" ) sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 100, beta = 0.2, gamma = 0.1) ) sir_results = mp_trajectory(sir_simulator) set.seed(101) sir_prevalence = (sir_results     |> dplyr::select(-c(row, col))     |> filter(matrix == \"I\")     |> mutate(obs_val = value + rnorm(n(), sd = 1)) ) gg0 <- ggplot(sir_prevalence, aes(time)) +     geom_point(aes(y = obs_val)) +     geom_line(aes(y = value)) print(gg0)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-1-add-calibration-information","dir":"Articles","previous_headings":"‘Hello, World’: an easy (??) calibration exercise","what":"Step 1: add calibration information","title":"Advanced Calibration","text":"Now ’ll use experimental mk_calibrate() function macpan2helpers package Unlike typical R functions, function modifies sim object place (!!) FIXME: place -- make clone, easy oor sanity check: make sure starting values give reasonable-looking trajectory.  simulated trajectory sensible case - log_beta value way large (set default exp(1)≈{\\exp(1) \\approx} 2.72), know case true value 0.2). Hopefully real system know enough get reasonable order--magnitude starting values. (really knew γ≈0.1\\gamma \\approx 0.1, know starting value log(β)=1\\log(\\beta)=1 correspond ${\\cal R}_0 \\approx 28$, clearly unrealistic infectious diseases … Setting log(β)=0\\log(\\beta)=0 instead gives us trajectory still unrealistic (peak observed prevalence 16.7), least ’s smooth. turns good enough, finding appropriate starting values (based external information trial error) often significant part modeling workflow.  Let’s replace starting value log_beta 0: (proper workflow might prefer go back upstream wherever defined default values, rather resetting value fly …)","code":"macpan2helpers::mk_calibrate(sir_simulator,    data = data.frame(I_obs = sir_prevalence$obs_val),    params = list(beta = 1, I_sd = 1),    transforms = list(beta = \"log\", I_sd = \"log\"),    exprs = list(log_lik ~ dnorm(I_obs, I, I_sd)) ) (sir_simulator   |> mp_trajectory()  |> filter(matrix == \"I\")  |> ggplot(aes(time, value))   + geom_line() ) (sir_simulator$report(c(0,0)) |>  filter(matrix == \"I\") |>  ggplot(aes(time, value)) + geom_line() ) sir_simulator$replace$params(     c(0         , 1         )   , c(\"log_beta\", \"log_I_sd\") )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-2-do-the-fit","dir":"Articles","previous_headings":"‘Hello, World’: an easy (??) calibration exercise","what":"Step 2: do the fit","title":"Advanced Calibration","text":"Print results nlminb - always check value convergence code (’s 0, something may gone wrong …) Back-transform parameters: Get information (little uglier …) correspond true values 0.2, 1, pretty close. fixme: can handle back-transformation/parameter naming nicely? coef(), summary() methods … ?? best-fit parameters stored internally, re-run $report() method get information predicted best-fit trajectory:","code":"fit <- sir_simulator$optimize$nlminb() print(fit) #> $par #>      params      params  #> -1.61413121 -0.07942465  #>  #> $objective #> [1] 133.9514 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 12 #>  #> $evaluations #> function gradient  #>       18       13  #>  #> $message #> [1] \"relative convergence (4)\" exp(fit$par) #>    params    params  #> 0.1990635 0.9236476 coefnames <- function(x) {     x$current$params_frame()$mat } drop_trans <- function(x) gsub(\"(log|logit)_\", \"\", x) ff <- sir_simulator$ad_fun() class(ff) <- \"TMB\" (broom.mixed::tidy(ff, conf.int = TRUE)     |> select(-c(type, std.error))     |> mutate(term = drop_trans(coefnames(sir_simulator)))     |> mutate(across(where(is.numeric), exp))     |> as_tibble() ) #> outer mgc:  1.118671e-09  #> outer mgc:  63.85069  #> outer mgc:  63.73186  #> outer mgc:  0.1998001  #> outer mgc:  0.2002001  #> outer mgc:  145.0178 #> # A tibble: 2 × 4 #>   term  estimate conf.low conf.high #>   <chr>    <dbl>    <dbl>     <dbl> #> 1 beta     0.199    0.198     0.201 #> 2 I_sd     0.924    0.804     1.06 sim_vals <- (sir_simulator   |> mp_trajectory()   |> filter(matrix == \"I\") ) gg0 + geom_line(data = sim_vals, aes(y= value), colour = \"red\")"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"a-slightly-harder-more-realistic-example","dir":"Articles","previous_headings":"","what":"A slightly harder, more realistic example","title":"Advanced Calibration","text":"’ll show alternate choices made. ’ll (1) use real data instead simulated; (2) fit beta gamma, (3) use negative binomial response (needs dispersion parameter I_disp instead standard deviation …) look default parameters? (save typing ’m writing generic function runs model specified set parameters, plots results along data.) fixme: basic plotting functionality macpan2helpers ?  great: helps bump value beta (ℛ0=4\\mathcal{R}_0 = 4):  optimize$nlminb() fails (obscurely) first set starting values, works OK increase beta: fixme: (1) clarify default parameters need transformed (.e. work $replace$params(log(c(1, 0.5, 1)), ...)); (2) save loglik values per point can see original (untransformed) values (1, 0.5, 1) lead infinite log-likelihoods, even think ’re clamping variables … ?? (simulated output doesn’t look crazy …)  fit isn’t perfect, can think number reasons (people complicated; model tracking number current infected children, data numbers children bed; haven’t allowed exposed class …).","code":"library(outbreaks) sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 763, I = 3, beta = 1, gamma = 0.5) ) macpan2helpers::mk_calibrate(sir_simulator   , data = data.frame(I_obs = influenza_england_1978_school$in_bed)   , params = list(beta = 1, gamma = 0.5, I_disp = 1)   , transforms = list(beta = \"log\", gamma = \"log\", I_disp = \"log\")   , exprs = list(log_lik ~ dnbinom(I_obs, I, I_disp)) ) sir_simulator$objective(log(c(1, 0.5, 1))) #> [1] 94.70146 sim_plot <- function(pars = log(c(1, 0.5, 1))) {     predvals <- (sir_simulator$report(pars)         |> filter(matrix == \"I\")         |> select(time, I_obs = value)         |> bind_cols(influenza_england_1978_school)     )     ggplot(predvals, aes(time, I_obs)) + geom_line() +         geom_point(aes(y= in_bed)) +         labs(x=\"time\", y = \"I/'in bed'\") } sim_plot() sim_plot(pars = log(c(2, 0.5, 1))) sir_simulator$replace$params(log(c(2, 0.5, 1)), c(\"log_beta\", \"log_gamma\", \"log_I_disp\")) fit <- sir_simulator$optimize$nlminb() #> outer mgc:  38.61651  #> outer mgc:  16.53627  #> outer mgc:  6.449698  #> outer mgc:  48.42602  #> outer mgc:  33.06605  #> outer mgc:  2.831973  #> outer mgc:  0.6015714  #> outer mgc:  0.009401567  #> outer mgc:  1.102318e-06 sim_plot(pars = fit$par)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"computing-and-plotting-confidence-and-prediction-intervals","dir":"Articles","previous_headings":"A slightly harder, more realistic example","what":"Computing and plotting confidence and prediction intervals","title":"Advanced Calibration","text":"code isn’t horribly complex, hopefully somewhat streamlined/automated future. Computing confidence prediction intervals fairly big subject; see Bolker (2008) chapter 7 introduction issues.  intervals based delta method, approximate (nearly CIs approximations, delta method assumes (1) multivariate normality sampling distribution (2) quadratic approximation nonlinearities model). can see leads negative values within CI range points … confidence intervals, prediction intervals (don’t necessarily expect points lie within envelope); prediction intervals non-Normal errors little bit tricky (maybe something Bolker 2008?), worth right now. can also generate intervals based multivariate normal sampling, relaxes second assumption first. Sometimes calculating standard deviations predictions memory-hungry, show get covariance matrix parameters directly fit (take extra computation).  case delta-method (dotted lines) ensemble CIs (ribbons) different (can see ensemble CIs take care negative values CI); certainly wouldn’t badly misled delta method CIs case. Since running ensemble requires many (typically 500-1000) independent runs $report() method, may want computation parallel. , can use many available tools R, example: (parallel::parApply base R, doParallel/foreach, future/furrr, etc.) small models may take longer copy TMBsimulator object different workers takes run ensemble … can also compute prediction intervals via ensemble, adding appropriate amount negative binomial noise simulation. However, makes sense add observation error time series (one observed time series probably want estimate separate dispersion parameters series), ’ll adapt ensemble code pick values adding noise:  Unsurprisingly, prediction intervals (ribbon) much wider delta-method ensemble-quantile (dashed dotted lines) intervals.","code":"obs <- data.frame(     time = seq(nrow(influenza_england_1978_school))   , value = influenza_england_1978_school$in_bed ) res = (sir_simulator$report_with_sd()   |> mutate(         var = factor(matrix, levels = c(\"S\", \"I\", \"R\"))       , lwr_delta = value - 1.96 * sd       , upr_delta = value + 1.96 * sd     ) ) #> outer mgc:  1.102318e-06  #> outer mgc:  2.135549  #> outer mgc:  2.137124  #> outer mgc:  0.5301401  #> outer mgc:  0.5279329  #> outer mgc:  0.007252414  #> outer mgc:  0.007242536 gg_base <- (res   |> ggplot(aes(x = time, y = value))    + geom_line(aes(colour = var))    + geom_point(data = obs) ) gg_ci1 <- (gg_base    + geom_ribbon(         aes(ymin = lwr_delta, ymax = upr_delta, fill = var)       , alpha = 0.3, colour = NA     ) ) print(gg_ci1) sdr = sir_simulator$sdreport() set.seed(101) nsim <- 1000 par <- fit$par H <- numDeriv::jacobian(sir_simulator$ad_fun()$gr, par) #> outer mgc:  1.102318e-06  #> outer mgc:  0.1175492  #> outer mgc:  0.1175562  #> outer mgc:  0.03944411  #> outer mgc:  0.03943403  #> outer mgc:  0.002035877  #> outer mgc:  0.002034903  #> outer mgc:  0.05877466  #> outer mgc:  0.05877806  #> outer mgc:  0.01971997  #> outer mgc:  0.0197191  #> outer mgc:  0.001017896  #> outer mgc:  0.001017494  #> outer mgc:  0.02938693  #> outer mgc:  0.02938943  #> outer mgc:  0.009859049  #> outer mgc:  0.009860486  #> outer mgc:  0.000508977  #> outer mgc:  0.0005087181  #> outer mgc:  0.01469295  #> outer mgc:  0.01469523  #> outer mgc:  0.004928877  #> outer mgc:  0.00493089  #> outer mgc:  0.0002545353  #> outer mgc:  0.0002543122 ## FIXME: why doesn't this match? ## H0 <- with(sir_simulator$ad_fun(), optimHess(par, fn = fn, gr = gr)) Sigma <- solve(H) stopifnot(all.equal(Sigma, unname(sdr$cov.fixed), tolerance = 1e-5)) ## sample from (assumed) multivariate normal distribution of parameters parvals <- MASS::mvrnorm(nsim, mu = par, Sigma = Sigma) ## simulate for each parameter set sim_ensemble <- apply(parvals, 1, function(p) sir_simulator$report(p, .phases = \"during\")$value) ## 42 x 1000 ## compute 95% quantiles across runs (pointwise) mk_quantiles <- function(ensemble, suffix = \"ens\", level = 0.95) {     sim_quantiles <- (t(apply(ensemble, 1, quantile, c((1-level)/2, (1+level)/2)))         |> as.data.frame()         |> setNames(sprintf(c(\"lwr_%s\", \"upr_%s\"),  suffix))     ) } ## attach to existing data res2 <- cbind(res, mk_quantiles(sim_ensemble)) ## plot gg_ci2 <- (gg_base %+% res2) +     geom_ribbon(aes(ymin = lwr_delta, ymax = upr_delta, colour = var), lty = 2, fill = NA) +     geom_ribbon(aes(ymin = lwr_ens, ymax = upr_ens, fill = var), colour = NA, alpha = 0.3) print(gg_ci2) library(parallel) ncores <- max(1, getOption(\"ncores\", round(detectCores()/2))) cl <- makeCluster(ncores) clusterExport(cl = cl, \"sir_simulator\") ## may take a little while sim2 <- parApply(cl = cl,                  parvals, 1,                  function(p) sir_simulator$report(p, .phases = \"during\")$value) stopCluster(cl) stopifnot(all.equal(sim_ensemble, sim2)) ## identical ## negative binomial dispersion ('size') parameter ## (should be able to do this more nicely with a coef() method ... nb_disp <- exp(fit$par[3])   sim_ensemble2 <- apply(parvals, 1,                        function(p) {                            ## FIXME: misspelling '.phases' gives a 'wrong parameter length arg                            s <- sir_simulator$report(p, .phases = \"during\")                            v <- s$value[s$matrix == \"I\"]                            ## force mean to be non-negative                            ## we could also accept the warnings/NA values from negative predictions                            rnbinom(length(v), mu = pmax(0, v), size = nb_disp)                        }) I_ens <- data.frame(time = obs$time, var = \"I\", mk_quantiles(sim_ensemble2, suffix = \"predens\")) ## attach to existing data res3 <- full_join(res2,  I_ens, by = c(\"time\", \"var\")) ## plot gg_ci3 <- (gg_base %+% res3) +     geom_ribbon(aes(ymin = lwr_delta, ymax = upr_delta, colour = var), lty = 2, fill = NA) +     geom_ribbon(aes(ymin = lwr_ens, ymax = upr_ens, colour = var), lty = 3, fill = NA) +     geom_ribbon(aes(ymin = lwr_predens, ymax = upr_predens, fill = var), colour = NA, alpha = 0.3) ## suppress warnings about 'no non-missing args' [because we don't have *_predens vars for S and R] suppressWarnings(     print(gg_ci3)     )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"hamiltonian-mc","dir":"Articles","previous_headings":"","what":"Hamiltonian MC","title":"Advanced Calibration","text":"development Since Markov chain Monte Carlo samples wider range parameter space, ’s easier get numerical troubles - especially since haven’t specified prior distributions. can mitigate problems slightly (1) specifying random-number seed (least problems reproducible) (2) specifying starting conditions rather allowing Stan pick random. Starting best-fit parameters works, conservative - ideally want make sure chains start different points. second strategy use best-fit parameters baseline, jitter randomly ±40%. (diagnostics - check divergent transitions, look R̂\\hat R, traceplots, etc etc; see e.g. bayestestR::diagnostic_posterior(), bayeslot::mcmc_rank_overlay(), shinyStan … brief examples .) case MCMC quantile credible intervals (ribbons) pretty close delta-method MVN ensemble CIs (shown dotted lines) …","code":"library(tmbstan) stan1 <- tmbstan(sir_simulator$ad_fun(), seed = 101, init  = \"last.par.best\") #> Warning in tmbstan(sir_simulator$ad_fun(), seed = 101, init = \"last.par.best\"): #> Re-cycling inits to match number of chains init_fun <- function(jitter = 0.4) {     p <- sir_simulator$ad_fun()$env$last.par.best     p * runif(length(p), 1-jitter, 1+jitter) } stan2 <- tmbstan(sir_simulator$ad_fun(), init = init_fun, seed = 101) broom.mixed::tidy(stan2, conf.int = TRUE) #> # A tibble: 3 × 5 #>   term      estimate std.error conf.low conf.high #>   <chr>        <dbl>     <dbl>    <dbl>     <dbl> #> 1 params[1]    0.554    0.0324    0.498     0.627 #> 2 params[2]   -0.750    0.0700   -0.881    -0.613 #> 3 params[3]    2.54     0.558     1.37      3.59 mcmc_pars <- as.data.frame(stan2, pars = \"lp__\", include = FALSE) sim_mcmc <- apply(mcmc_pars, 1, function(p) sir_simulator$report(p, .phases = \"during\")$value) ## 48 x 1000 I_mcmc <- data.frame(time = obs$time, var = \"I\", mk_quantiles(sim_mcmc, suffix = \"mcmc\")) ## attach to existing data res4 <- cbind(res3,  mk_quantiles(sim_mcmc, suffix = \"mcmc\")) gg_ci4 <- (gg_base %+% res4) +     geom_ribbon(aes(ymin = lwr_delta, ymax = upr_delta, colour = var), lty = 2, fill = NA) +     geom_ribbon(aes(ymin = lwr_ens, ymax = upr_ens, colour = var), lty = 3, fill = NA) +     geom_ribbon(aes(ymin = lwr_mcmc, ymax = upr_mcmc, fill = var), colour = NA, alpha = 0.3) ## suppress warnings about 'no non-missing args' [because we don't have *_predens vars for S and R] suppressWarnings(     print(gg_ci4)     )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"alternative-confidence-intervals","dir":"Articles","previous_headings":"","what":"Alternative confidence intervals","title":"Advanced Calibration","text":", can also get likelihood profile CIs …","code":"ff <- sir_simulator$ad_fun() class(ff) <- \"TMB\" (broom.mixed::tidy(ff, conf.int = TRUE, conf.method = \"profile\")     |> select(-c(type, std.error))     |> mutate(term = drop_trans(coefnames(sir_simulator)))     |> mutate(across(where(is.numeric), exp))     |> as_tibble() )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"irregular-data-multiple-data-streams","dir":"Articles","previous_headings":"","what":"Irregular data; multiple data streams","title":"Advanced Calibration","text":"now ’re going revert previous fake/simulated data. ’ll fit infection prevalence number recovered, adding negative binomial observation noise dropping 50% (approximately) observations random  Numbers samples missing observations: fixme: add information original 1978-influenza article probable starting date, duration, natural history? Comparison fitode ? priors/regularization?? (statistical) diagnostics? e.g. compute residuals, plot vs. time vs fitted values, scale-location plot, etc. ? CI stuff: importance sampling, Juul et al. functional ribbons, … simple time-varying parameters fitting multiple data streams (progress) irregularly sampled data (progress) estimate starting values accumulators/differences: prevalence, deaths forecasting/scenarios","code":"sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 100, beta = 0.2, gamma = 0.1) ) ## `.phases = \"during\"` is important so that the number of observations matches the number of time steps sir_results = sir_simulator$report(.phases = \"during\") set.seed(101) subsamp <- function(x, missprob = 0.5) { x[runif(length(x))<missprob] <- NA; x }  sir_simdat <- (sir_results     |> select(time, matrix, value)     |> filter(matrix %in% c(\"I\", \"R\"))     |> pivot_wider(names_from = \"matrix\", values_from = \"value\")     |> mutate(I_obs = subsamp(rnbinom(n(), mu = I, size = 4)),               R_obs = subsamp(rnbinom(n(), mu = R, size = 8)))     |> select(time, I_obs, R_obs) ) ## re-pivot for plotting purposes ... plotdat <- sir_simdat |> pivot_longer(-time, names_to = \"var\", values_to = \"count\") ggplot(plotdat, aes(time, count, colour = var)) + geom_point() +     geom_smooth(method = \"gam\", method.args = list(family = quasipoisson)) #> `geom_smooth()` using formula = 'y ~ s(x, bs = \"cs\")' #> Warning: Removed 91 rows containing non-finite outside the scale range #> (`stat_smooth()`). #> Warning: Removed 91 rows containing missing values or values outside the scale range #> (`geom_point()`). with(sir_simdat, table(I_missing=is.na(I_obs), R_missing=is.na(R_obs))) #>          R_missing #> I_missing FALSE TRUE #>     FALSE    31   23 #>     TRUE     24   22 ## won't work yet ... need more sophisticated obs/sim matching ... # mk_calibrate(sir_simulator, #              data = sir_simdat, #              params = list(beta = 1, gamma = 0.5, I_disp = 1, R_disp = 1), #              transforms = list(beta = \"log\", gamma = \"log\", I_disp = \"log\", R_disp = \"log\"), #              exprs = list(log_lik ~ dnbinom(I_obs, I, I_disp) + #                           dnbinom(R_obs, R, R_disp)) #              )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"hello-world-the-hard-way","dir":"Articles","previous_headings":"","what":"‘Hello, World’ the hard way","title":"Advanced Calibration","text":"section explains going hood macpan2helpers::mk_calibrate()","code":""},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-0-recreate-the-simulator","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 0: recreate the simulator","title":"Advanced Calibration","text":"Since trying add matrix simulator twice causes error, ’ll create new instance simulator:","code":"sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(N = 100, beta = 0.2, gamma = 0.1) )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-1-add-observed-data-and-slots-for-history-etc-","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 1: add observed data and slots for history etc.","title":"Advanced Calibration","text":"files model library sufficient define simulator, now need add structure model object can calibration - specifically, whatever observed data want compare , whatever new variables (“matrices”) expressions evaluate compute goodness fit (aka loss function objective function) particular set parameters. TMBSimulator object (.e., sir_simulator example), $add$matrices() method add new variables space object already stored state variables, etc. (use sir_simulator$matrix_names() list existing matrices, although produces long, scary list internal variables macpan2 constructed) Now use $add$matrices() : add observed data declare matrix storing simulation history variables compare observed data declare matrix store log-likelihood specify matrices save /return report fixme: possibly comment added objects -front, definition files … fixme: examples show sir_simulator$print$matrix_dims() point. good /interpret ?","code":"sir_simulator$add$matrices(   ## observed data   I_obs = sir_prevalence$obs_val,   ## simulated trajectory to compare with data   I_sim = empty_matrix,    ## matrix to contain the log likelihood values at each time step   log_lik = empty_matrix,   ## need to save the simulation history of each of these matrices   .mats_to_save = c(\"I_sim\", \"log_lik\"),   .mats_to_return = c(\"I_sim\", \"log_lik\") )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-2-collect-simulated-values","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 2: collect simulated values","title":"Advanced Calibration","text":"Collect simulated values matrices compared data. .= Inf .phase = \"\" indicates expression come end expressions evaluated iteration simulation loop. Like $add$matrices(), $insert$expressions adds components existing TMBSimulator object - case, expressions computed simulation. (example, since set .phase = \"\", expressions computed time step.) fixme: ’s best way handle irregularly sampled data/match timestamps observed data? (, footnote put ‘extra tricks’ section)","code":"sir_simulator$insert$expressions(   I_sim ~ I,   .phase = \"during\",   .at = Inf )"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-3-set-up-and-compute-objective-function","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 3: set up and compute objective function","title":"Advanced Calibration","text":"use log (default) Gaussian density observed values mean (.e. predicted) value simulated values (equivalent least-squares estimation, added complication estimate standard deviation explicitly rather computing residuals). Add new parameter (standard deviation observed distribution around predicted values) rbind_time function gathers together full simulation history I_sim matrix binding together rows iteration. Define objective function (almost always sum negative log-likelihoods point):","code":"sir_simulator$add$matrices( I_sd = 1 ) sir_simulator$insert$expressions(   log_lik ~ dnorm(I_obs, I_sim, I_sd),   .phase = \"after\"   ) sir_simulator$replace$obj_fn(~ -sum(log_lik))"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-4-declare-andor-transform-parameters-to-be-optimized-set-starting-values","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 4: declare and/or transform parameters to be optimized, set starting values","title":"Advanced Calibration","text":"postponed defining I_sd model step (fixme: right?), confusing since used objective function. parameters restricted positive, almost always best estimate log scale. ensures values always non-negative (positive unless transformed values negative large enough magnitude exp(x) underflows zero) advantages optimization (fixme: much detail needed ? Shrink scale optimization, make parameter magnitudes ${\\cal O}(1)$, make Wald estimation reliable …) practice often read parameter starting values CSV file (using read.csv base R readr::read_csv() tidyverse), can set data frame fly Using $add_transformations(Log(\"var\")) automatically adds variable called log_var list matrices.","code":"sir_simulator$add$transformations(Log(\"I_sd\")) sir_simulator$add$transformations(Log(\"beta\")) params <- read.delim(sep = \"|\", header = TRUE,                      text = \" mat       | default log_I_sd  | 0 log_beta  | 1 \") sir_simulator$replace$params_frame(params)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"step-5-do-the-fit","dir":"Articles","previous_headings":"‘Hello, World’ the hard way","what":"Step 5: do the fit","title":"Advanced Calibration","text":"’s always good idea quick sanity checks objective function try optimize: get finite values (reasonable inputs)? changing inputs change returned value? get error messages running objective function, sir_simulator$report() help debug printing expression gave rise errors. sir_simulator$get$initial(<varname>) print initial values used, sir_simulator$current$params_frame() print full parameter data frame. fixme: easier way substitute single parameter value? Way modify starting conditions optimizer fly? (Specifying start argument gives ‘formal argument “start” matched multiple actual arguments’ – “replace present” functionality)","code":"sir_simulator$objective(c(1,1)) #> [1] 776.0665 sir_simulator$objective(c(0,1)) #> [1] 4408.378 fit <- sir_simulator$optimize$nlminb()"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"measles-data-in-progress","dir":"Articles","previous_headings":"","what":"Measles Data – In-Progress","title":"Advanced Calibration","text":"reasonably difficult problem – fit SIR model weekly measles incidence data London UK six decades.  need use slightly extended version SIR specification includes waning immunity. use radial basis functions model time-variation transmission rate. also make variety questionable assumptions (TODO: fix ), point moment just illustrate usage provide proof concept. example simulation model, fitting data.  looks nothing like observed measles series, illustrates ability generate complex incidence patterns present simple SIR model without radial basis functions waning immunity. modify simulation object able fit measles data. optimization takes quite minutes, still doesn’t converge 10000 function evaluations. red data fitted black observed. perfect fit, bad now (TODO: work , without papering real challenges).","code":"measles = read.csv(   file.path(     \"https://raw.githubusercontent.com/davidearn/iidda/master/data\",     \"meas_uk__lon_1944-94_wk/source-data/meas_uk__lon_1944-94_wk.csv\"   ),   comment = \"#\" ) measles$date = as.Date(sprintf(   \"%s-%s-%s\", measles$year, measles$month, measles$day )) plot(measles$date, measles$cases, type = \"l\") sir_waning = mp_tmb_library(\"starter_models\"   , \"sir_waning\"   , package = \"macpan2\" ) d = 100 n = nrow(measles) simulator = (sir_waning   |> mp_simulator(       time_steps = n     , outputs = c(\"S\", \"I\", \"R\", \"infection\")     , default = list(         N = 100000, I = 500       , gamma = 0.2, phi = 0.01       , X = rbf(n, d)       , b = rnorm(d, sd = 0.01)       , eta = empty_matrix     )   ) )      ## radial basis function evaluations simulator$insert$expressions(     eta ~ gamma * exp(X %*% b)   , .phase = \"before\"   , .at = Inf ) simulator$insert$expressions(     beta ~ eta[time_step(1)] / clamp(S/N, 1/100)   , .phase = \"during\"   , .at = 1 ) simulated_incidence = filter(simulator$report(.phases = \"during\"), matrix == \"infection\")$value plot(measles$date, simulated_incidence, type = \"l\", xlab = \"time\") simulator$add$matrices(     reports = measles$cases   , log_lik = empty_matrix   , sim_reports = empty_matrix ) simulator$insert$expressions(     sim_reports ~ rbind_time(infection)   , .phase = \"after\"   , .at = Inf ) simulator$replace$params(   default = c(       c(0.2, 0.01)     , rep(0, d)     , 500   )   , mat = c(       c(\"gamma\", \"phi\")     , rep(\"b\", d)     , \"I\"   )   , row = c(       rep(0, 2L)     , seq_len(d) - 1L     , 0L   ) ) simulator$replace$obj_fn(~ - sum(dpois(reports, sim_reports))) simulator$optimize$nlminb(control = list(eval.max = 10000, iter.max = 10000, trace = 10)) simulator$optimization_history$get()[[3]]  ## the 3 is there because we tried two other times simulated_incidence = filter(simulator$report(.phases = \"during\"), matrix == \"incidence\")$value plot(measles$date, measles$cases, xlab = \"time\", type = \"l\") lines(measles$date, simulated_incidence, col = 2)"},{"path":"https://canmod.github.io/macpan2/articles/calibration_advanced.html","id":"challenging-logistic-variation-in-transmission-rate","dir":"Articles","previous_headings":"","what":"Challenging Logistic Variation in Transmission Rate","title":"Advanced Calibration","text":"consider problem fitting SIR model simulated dataset model, simulations pose challenges fitting machinery. simulation model includes logistically time-varying transmission rate.  Fitting simulation data, manages converge, wrong value.  fit good! Even though fitting extact noiseless data generating model, fit good? find plot likelihood surface arrows representing magnitude direction -hill gradient towards optimum. Notice flat gradient direction along valley containing optimum (0,1)(0, 1). gradient pointing towards valley along . understand .   Explore carefully: fixme: causes spikiness along ridge? Add points optimization attempt stopped? experimental: working DEoptim (haven’t included yet don’t want Suggest: DEoptim … fixme: also add multi-start example (.e. less fancy DEoptim, suitable surfaces like one multimodal smooth (ref. Raue et al. “Lessons Learned Quantitative Dynamical Modeling Systems Biology” 2013)?) fixme: warning $current$params_vector() mutable/unreliable. Extractor $ad_fun()$env$last.par.best (equivalently optim fit)? fixme: add (abbreviated) sessionInfo output? (Package versions?)","code":"sir_simulator = mp_simulator(sir_spec   , time_steps = 100   , outputs = c(\"S\", \"I\", \"R\")   , default = list(       N = 100000, I = 500     , beta = 0.2, gamma = 0.2   ) ) n = 2500 set.seed(1L) simulator = (sir_spec   |> mp_simulator(       time_steps = n     , outputs = c(\"S\", \"I\", \"R\", \"beta\", \"infection\")     , default = list(         N = 100000, I = 500       , beta = 0.2, gamma = 0.2       , X = cbind(1, scale(seq_len(n)))       , b = c(0, 1)       , beta_values = empty_matrix     )   ) ) simulator$insert$expressions(     beta_values ~ 1 / (1 + exp(-X %*% b))   , .phase = \"before\"   , .at = Inf ) simulator$insert$expressions(     beta ~ beta_values[time_step(1)]   , .phase = \"during\"   , .at = 1 ) simulator$replace$params(     default = c(0, 1)   , mat = rep(\"b\", 2)   , row = 0:1 ) set.seed(5L) sims = mp_trajectory(simulator) (sims   |> rename(variable = matrix)   |> ggplot()   + facet_wrap(~ variable, ncol = 1, scales = 'free')   + geom_line(aes(time, value)) ) set.seed(3L) ## different seeds do result in convergence on the correct value reports = filter(sims, matrix == \"infection\")$value simulator$add$matrices(reports = reports, report_sim = empty_matrix) simulator$insert$expressions(     report_sim ~ rbind_time(infection)   , .phase = \"after\"   , .at = Inf ) simulator$replace$obj_fn(~ -sum(dpois(reports, report_sim))) simulator$replace$params(     default = rnorm(2L) ## random starting values for the optimizer   , mat = rep(\"b\", 2)   , row = 0:1 ) simulator$optimize$nlminb() #> outer mgc:  11268970  #> outer mgc:  7215054  #> outer mgc:  3087372  #> outer mgc:  3522804  #> outer mgc:  470268.8  #> outer mgc:  802897.8  #> outer mgc:  133686.6  #> outer mgc:  4449.854  #> outer mgc:  5.260259  #> outer mgc:  7.984454e-06 #> $par #>     params     params  #> -1.0929130  0.1633477  #>  #> $objective #> [1] 326073.6 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 9 #>  #> $evaluations #> function gradient  #>       12       10  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" simulator$current$params_frame() #>   par_id mat row col    default    current #> 1      0   b   0   0 -0.9619334 -1.0929130 #> 2      1   b   1   0 -0.2925257  0.1633477 fitted_incidence = (simulator$current$params_vector()   |> simulator$report()   |> filter(matrix == \"infection\")   |> pull(value) ) plot(reports, type = \"l\") lines(fitted_incidence, col = 2) make_liksurf <- function(lwr = c(-1, 0), upr = c(1, 2),                          n = c(41, 41)) {     lik_surf = expand.grid(         intercept_parameter = seq(from = lwr[1], to = upr[1],                                    length.out = n[1]),         slope_parameter = seq(from = lwr[2], to = upr[2],                               length.out = n[2])     )     gr = t(apply(lik_surf, 1, simulator$gradient))     lik_surf$z = apply(lik_surf, 1, simulator$objective)     gr = 0.1 * gr / max(abs(gr))     lik_surf$gx = gr[,1]     lik_surf$gy = gr[,2]     return(lik_surf) } lik_surf <- make_liksurf() mk_plot <- function(dd, arrows = TRUE, contours = TRUE,                     arrow_len = 0.05,                     cbrks = (1:10)*1e5) {     gg0 <- (ggplot(dd, aes(intercept_parameter, slope_parameter))         + geom_tile(aes(fill = z))         + theme_bw()         + scale_x_continuous(expand = c(0,0))         + scale_y_continuous(expand = c(0,0))         + annotate(geom = \"point\", x = 0, y = 1, colour = \"yellow\", size = 2,                    pch = 16)         + scale_fill_continuous(trans = \"log10\")      )     if (contours) {         gg0 <- gg0 + geom_contour(aes(z = z), colour = \"red\",                                   breaks = cbrks)     }     if (arrows) {         gg0 <- gg0 + geom_segment(                          data = dd[seq(nrow(dd)) %% 5 == 0 , ],                          aes(                              xend = intercept_parameter - gx,                               yend = slope_parameter - gy                          ),                           arrow = arrow(length = unit(arrow_len, \"inches\")),                           colour = 'white'                      )     }     gg0 } print(mk_plot(lik_surf)) lik_surf2 <- make_liksurf(lwr = c(-0.1, 0.9), upr = c(0.1, 1.1)) print(mk_plot(lik_surf2, arrows = FALSE, cbrks = 1e4*(1:10))) make_mat <- function(x) {   with(x, matrix(z, sqrt(length(z)),             dimnames = list(intercept = unique(intercept_parameter),                             slope = unique(slope_parameter)))        ) } library(rgl) z1 <- make_mat(lik_surf) persp3d(as.numeric(rownames(z)), as.numeric(colnames(z)), log10(z),         col = \"gray\") z2 <- make_mat(lik_surf2) persp3d(as.numeric(rownames(z2)), as.numeric(colnames(z2)), log10(z2),         col = \"gray\") library(DEoptim) set.seed(101) fit <- DEoptim(simulator$objective, lower = rep(-10, 2), upper = rep(10, 2)) fitted_incidence = (simulator$ad_fun()$env$last.par.best     |> simulator$report()     |> filter(matrix == \"infection\")     |> pull(value) ) plot(reports, type = \"l\") lines(fitted_incidence, col = 2)"},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"introduction","dir":"Articles","previous_headings":"","what":"Introduction","title":"Composing Related Simulation Models","text":"defining epidemiological model users often want compute quantities summarize . Examples include simple single-number quantities like R0, Gbar, r, well elaborate objects like stable compartment distribution linearized model. Methods computing summaries arbitrary models deep research area, making difficult include general purpose software. However, always (strong?) possible use brute force simulation methods approximating values. simulation approach take McMasterPandemic. approach modify focal model simulations modified model can used approximate summaries focal model. example, one scale population size 1 zeros compartments except one exposed category. Simulations cohort models generate force infection time-series, turns sum finite length time-series approximation R0. Sometimes summaries computed descriptive purposes, focus use semi-automatically refining calibrations. example, calibrations can often improved including prior information model parameters using Bayesian estimation. can easier get prior information summaries like R0 model parameters. case one might want regularize calibrations using priors R0. another example, helps initialize state vector simulation model using eigenvector linearization focal model. eigenvector often interpretable stable compartment distribution, unrealistic model fluctuations near beginning epidemic often minimized. Another use case model composition occurs online forecasting. forecasts made every n days, forecast n-day period. forecasts model can improved. One simple way carry information previous forecasts forward next forecasting model use final value state vector initial value new model. cases, start focal model generate several related models computing summaries like R0, eigenvectors, final state vectors. combine outputs models produce improved calibrations focal model.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"notation-and-theory","dir":"Articles","previous_headings":"","what":"Notation and Theory","title":"Composing Related Simulation Models","text":"developing general modelling software, need general theory assumptions. trajectory model model following. Takes parameter vector, θ\\theta, initial state vector, xx Simulates changes xx, referred trajectories Compares simulations observed time-series, yy Returns objective function measures deviation simulated trajectories observed time-series trajectory model contains two functions. function, g(θ;x)g(\\theta; x), parameter initial state vector, returns final state vector objective function, f(θ;x;y)f(\\theta; x; y) often omit yy notational compactness simply write f(θ;x)f(\\theta; x). One may estimate θ\\theta θ̂\\hat{\\theta} optimizing ff θ\\theta given xx yy. strategy xx must assumed. course user free try jointly calibrate θ\\theta xx. represent approach mathematically assuming θ\\theta can used determine xx. cases xx determined θ\\theta, omit xx write final state vector objective functions g(θ)g(\\theta) f(θ)f(\\theta). practice however, often enough information observed time series take approach. Furthermore, approach can computationally slow. discuss alternatives naive calibration approaches use single trajectory model. alternatives make use compositions combinations several related trajectory models. approaches focal trajectory model, focus inference forecasting. focal model able generate one models can used improve calibrations focal model.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"online-forecasting","dir":"Articles","previous_headings":"","what":"Online Forecasting","title":"Composing Related Simulation Models","text":"Consider sequence trajectory models result following sequence objective functions, f1(θ1;x1),...,fn(θn;xn)f_1(\\theta_1;x_1), ..., f_n(\\theta_n;x_n). simplicity, assume model state space potentially different parameter spaces. Let final state model ii gi(θi;xi)g_i(\\theta_i;x_i). Assume time split n+1n+1 equally-sized adjacent intervals θi\\theta_i calibrated data iith interval model ii used forecast data interval +1i+1. simple mechanism setting initial state vector models =1i = 1 set objective function +1i+1th model fi+1(θi+1;xi+1=gi(θ̂;xi))f_{+1}(\\theta_{+1};x_{+1} = g_i(\\hat{\\theta}_i;x_i)), θ̂\\hat{\\theta}_i calibrated parameter vector model ii. objective function fast evaluate relative objective function needs calibrate initial state vector. procedure work well forecasts sufficiently accurate forecast period. However, can improved upon fitting iith model forecasted data observed, using final state predicted model initial state next forecasting model.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"eigenvector-state-initialization","dir":"Articles","previous_headings":"","what":"Eigenvector State Initialization","title":"Composing Related Simulation Models","text":"previous online forecasting setup consider determine initial state vector, x1x_1, first model. approach achieving initialize state vector using eigenvector linearized version model. construct objective function fitting model assume two trajectory models parameter state space. Let initial state focal model given xx (possibly modified) eigenvector (possibly modified) linearized model given g0(θ)g_0(\\theta). let objective function focal model f(θ;x)f(\\theta;x). avoid needing specify fit reasonable value xx calibration step, one use following modified objective function, h(θ)=f(θ;x=g0(θ))h(\\theta) = f(\\theta;x = g_0(\\theta)). hidden computational difficulty however. McMasterPandemic uses TMB computational engine. TMB uses automatic differentiation efficiently provide gradients objective functions. Optimizers can make use gradients converge fewer iterations. However, TMB return gradients simulations respect parameters. means gradients return TMB f(θ;x=g0(θ))f(\\theta;x = g_0(\\theta)) take account effect θ\\theta xx g0g_0. means optimization using state-initialization approach able utilize TMB’s speed benefits.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"priors-on-r0","dir":"Articles","previous_headings":"","what":"Priors on R0","title":"Composing Related Simulation Models","text":"construct objective function, f(θ)f(\\theta) prior component one needs two related trajectory models, returns scalar-valued function model parameters, θ\\theta. focal model function, g(θ)g(\\theta), returns negative log likelihood cohort model function, h(θ)h(\\theta), approximates R0 returns negative log prior density value overall objective function given f(θ)=g(θ)+h(θ)f(\\theta) = g(\\theta) + h(\\theta), fast evaluate extent gg hh fast evaluate.","code":""},{"path":"https://canmod.github.io/macpan2/articles/composing_simulation_models.html","id":"regenerating-versus-reparameterizing-models","dir":"Articles","previous_headings":"","what":"Regenerating Versus Reparameterizing Models","title":"Composing Related Simulation Models","text":"framework can used model important computational reality using TMB, McMasterPandemic. want change initial state vector can either regenerating model new initial state, reparameterizing model changes parameter vector induce changes initial state. TMB, objective functions simulation functions can take one parameter vector. notation, model parameter vector θ\\theta. models require regeneration, f(θ;x)f(\\theta;x), assume xx constant feature model. change xx means recreating model objects including ff gg can much slower reparameterizing model, particularly want iteratively make changes state vector. Models explicit initial state, f(θ)f(\\theta), assume initial state can changed passing different parameter vector, θ\\theta, faster case model objects need iteratively regenerated. use cases , used regeneration approach. can modify use reparameterization.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"prerequisites","dir":"Articles","previous_headings":"","what":"Prerequisites","title":"The C++ Side","text":"document assumes solid understanding template model builder.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"matrices","dir":"Articles","previous_headings":"","what":"Matrices","title":"The C++ Side","text":"list numerical scalars, vectors, matrices passed input variables R C++. Scalars passed 1--1 matrices vectors n--1, numerical variables actually matrices. Treating numerical objects matrices might seem strange, similar R treats numerical objects vectors. way, R matrices vectors dimensions. just extending logic requiring vectors dimensions. restrictive R however allowing multidimensional arrays. Missing values allowed matrix. R side variables associated unique name, C++ side names associated 0-based index. indices spec 0-based. matrices must zero rows columns. matrix either zero rows zero columns empty matrix. Empty matrices allow placeholders matrices defined simulations. matrices passed using DATA_STRUCT(mats) TMB macro, associated C++ struct extracting component matrices index.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"parameters","dir":"Articles","previous_headings":"","what":"Parameters","title":"The C++ Side","text":"Two vectors parameters passed C++. PARAMETER_VECTOR(params) – vector becomes argument objective function, can therefore optimized using non-linear optimizer simulated using MCMC PARAMETER_VECTOR(random) – vector becomes random effects integrated objective function using Laplace approximation values parameter vectors used update certain elements matrix-valued variables within mats. elements updated described R side two data frames one row every matrix element replaced. data frames constructed R passed C++. columns data frame associated params following. DATA_IVECTOR(p_par_id) – indices params vector giving parameter use updating element mats updated DATA_IVECTOR(p_mat_id) – indices mats giving matrices elements replaced parameters DATA_IVECTOR(p_row_id) – indices rows within matrix associated element replaced parameters DATA_IVECTOR(p_col_id) – indices columns within matrix associated element replaced parameters vectors read C++, loop executed rows table replaces associated mats elements params elements. random vector treated similarly params associated data frame describing elements mats replaced. names columns table : DATA_IVECTOR(r_par_id) DATA_IVECTOR(r_mat_id) DATA_IVECTOR(r_row_id) DATA_IVECTOR(r_col_id) implied convention p stands ‘fixed Parameters’ r ‘Random parameters’.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"trajectory-simulation","dir":"Articles","previous_headings":"","what":"Trajectory Simulation","title":"The C++ Side","text":"input matrices mats updated using params random, matrices can modified. refer process modification trajectory simulation. three phases trajectory simulation process. simulation loop simulation loop simulation loop Simulation time measured dimensionless iterations, indexed integer, t, 0 <= t <= T+1, T number iterations loop. value matrix t = 0 value matrix just first iteration simulation loop begins. value matrix 0 < t < T+1 value matrix end tth iteration simulation loop. value matrix t = T+1 value matrix end simulation. time-indexing system used two purposes. optionally return simulation history user matrix modifications depend past values user can opt uses per-matrix basis, specifying two vectors one element per matrix. Equals 0 matrix overwritten simulation iteration, t Equals 1 computed values matrix saved Equals 0 matrix returned R side end simulation Equals 1 otherwise number iterations, T, passed TMB DATA_INTEGER(time_steps).","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"expressions","dir":"Articles","previous_headings":"","what":"Expressions","title":"The C++ Side","text":"mathematical details matrices modified simulation process controlled R side supplying expressions. expression right-hand-side R formula involving following three types objects. Names matrices mats Names functions currently allowed engine Numeric literals (e.g. 3.14) simulation sequential evaluation expressions user-specified order. expression may evaluated one three simulation phases – , , simulation loop. Expressions evaluated simulation loop evaluated , whereas evaluated loop evaluated every iteration. phase expression controlled DATA_IVECTOR(eval_schedule) vector described end section. mathematical expression can used C++ several ways. Information expression used passed C++ using set vectors. vectors length, one element per expression. Index mats identifying matrix produced expression Identifies whether expression evaluated inside SIMULATE macro within TMB value 0 indicates expression evaluated without SIMULATE macro (expect standard case), whereas value 1 indicates evaluation inside SIMULATE macro Note expression evaluated SIMULATE macro returned user mats_return == 1, must also returned within SIMULATE macro Number rows associated expression parse table (see section Parse Tables) expression evaluated order appears vectors. DATA_IVECTOR(eval_schedule) vector gives phase expressions evaluated. vector three elements giving number expressions evaluate , , simulation loop. particular first eval_schedule[0] expressions evaluated simulation loop, next eval_schedule[1] expressions evaluated every iteration simulation loop, next eval_schedule[2] expressions evaluated simulation loop. Inputs invalid sum elements eval_schedule equal number elements expr_output_id, expr_sim_block, expr_num_p_table_rows.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"parse-tables","dir":"Articles","previous_headings":"","what":"Parse Tables","title":"The C++ Side","text":"expression parsed table numbers represents expression can passed C++. row table corresponds step process evaluating expression. steps correspond one three types things, identified column n: function – n > 0 – see section Function Definitions matrix – n == 0 – see section Matrices literal – n == -1 – see section Literals row correspond function, column n gives number arguments function. column, x, gives index looking specific instance three types entities. example, n == 0 x column gives index mats list getting appropriate matrix n == -1 x gives index literals n > 0 x gives index list valid functions. column relevant functions, indicates row table representing first argument function. table processed C++ side recursive function either: rows associated functions: looks valid function list function definitions, recursively calls rows associated matrices: looks returns matrix mats list rows associated literals: looks returns literal list valid literals parse tables expressions concatenated row-wise passed C++ set three vectors equal length. DATA_IVECTOR(p_table_n) DATA_IVECTOR(p_table_x) DATA_IVECTOR(p_table_i) first three vectors correspond n, x, discussed section. expr_num_p_table_rows vector (defined section Expressions) used relate expression set rows concatenated parse table. elements vector contain number parse table rows associated expression. ordering elements consistent ordering concatenation individual parse tables, row indices necessary.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"literals","dir":"Articles","previous_headings":"","what":"Literals","title":"The C++ Side","text":"global list valid literals expressions passed C++ numeric vector, DATA_VECTOR(literals).","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"function-definitions","dir":"Articles","previous_headings":"","what":"Function Definitions","title":"The C++ Side","text":"functions used [Expression] must valid list functions defined C++ side. functions analogues R side make easy possible R users reason expressions. Valid functions take one matrix-valued arguments return single matrix. number arguments need known model defined, functions may optionally require predefined number arguments. Extending functionality engine typically involve simply adding function definitions list valid functions. function definitions following objects available . r – list matrices giving arguments function (e.g. r[0] returns first matrix). index2mats – list integers giving indices identifying matrices mats list (e.g. index2mats[0] returns index first argument). t – Time step hist – list lists matrices giving history simulation (e.g. hist[4][0] returns value first matrix time step 4). n – number arguments. Function definitions grouped types several functions require similar processing. main example element-wise binary operators, including +, *, -, /, ^. functions require pre-processing make sure matrix dimensions two operands compatible compatibility conveniently defined user.","code":""},{"path":"https://canmod.github.io/macpan2/articles/cpp_side.html","id":"objective-function","dir":"Articles","previous_headings":"","what":"Objective Function","title":"The C++ Side","text":"return value objective function expression depend values matrices end simulation entire saved simulation history. expression passed parse table. DATA_IVECTOR(o_table_n) DATA_IVECTOR(o_table_x) DATA_IVECTOR(o_table_i) implied convention o ‘Objective function parse table’ p ‘matrix Parse table’.","code":""},{"path":"https://canmod.github.io/macpan2/articles/debugging.html","id":"choosing-a-debugging-technique","dir":"Articles","previous_headings":"","what":"Choosing a Debugging Technique","title":"Debugging","text":"traceback(m = 1) options(error = recover) debug({package-function}) oor_debug$flag({object-method})","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"information-processing","dir":"Articles","previous_headings":"","what":"Information Processing","title":"Design Concepts","text":"Like statistical modelling software, high-level purpose macpan2 process data sources (top-left) results (bottom-left). case macpan2, processing done using compartmental modelling (right). major steps information processing numbered diagram, describe . Information processing begins accessing preparing numerical information various data sources, output standard numerical R objects. Depending nature analysis follow, information include default values parameters (e.g. transmission rate), initial values state variables (e.g. initial number infectious individuals), operational schedules (e.g. timing lockdown events vaccine roll-schedules), data model fitting (e.g. time series hospital utilization). step involve connecting real-time surveillance platforms reading static data files. functionality within macpan2 conducting step – macpan2 try reinvent wheel data access preparation. (2a) model chosen model library read R, optionally updating model structure using engine-agnostic model specification language. (2b) model written scratch using engine-agnostic model specification language. (2c) model written scratch using one engine-specific model specification languages. three alternatives, 2a chosen 2b 2c automatically executed 2b chosen 2c automatic. choice just close (2c) far (2a) actual computation engine want specifying models. several considerations choosing model specification workflow deciding alternative use. matter approaches taken, output step 2 model simulator can used generate modelling outputs like simulated incidence time-series reproduction numbers. Although model simulators come default initial values can used immediately, typically one like modify values without needing edit model specifications step 2. two main use-cases involving numerical modifications model simulators: order formally calibrate model parameters fitting model observed time-series data /modifying default parameter values reflect -scenario. use-cases, model simulator used input another model simulator produced output. model defining numerical initialization steps completed, model outputs produced long-format data frames. Finally model outputs incorporated forecasts, plots, reports, diagnostics using standard tools outside macpan2.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"modularity","dir":"Articles","previous_headings":"","what":"Modularity","title":"Design Concepts","text":"Modularity key principle macpan2 design ways. First, macpan2 meant plug standard R workflows data pre-processing simulation post-processing. little functionality macpan2 configuring data prepared input modelling outputs processed. Instead, macpan2 accepts standard data objects (data frames, matrices, vectors) returns simulations long-format data frames can processed using standard tools like dplyr ggplot2. design principle illustrated architecture diagram blue steps representing standard non-macpan2 workflows red steps representing workflows depend macpan2 data structures objects. challenges building red steps big enough prefer avoid reinventing wheel pre- post-processing. Second, macpan2 uses engine plug-architecture. Models defined engine-agnostic model specification language can rendered particular computational engine multiple computational approaches can used generate modelling outputs single model definition. can useful different model outputs efficient convenient different computational approaches. example, engines TMB capable automatic differentiation great fast optimization parameters computing ℛ0\\mathcal{R}_0 models arbitrary complexity, whereas engines Adaptive Tau better stochastic simulation techniques like Gillespie algorithm. Sometimes engine unable generate particular output sufficient difficulty part user render use-case practically impossible. example, possible conveniently utilize differential equation solvers TMB engine, limiting Euler simple RK4-type solvers. able swap TMB engine one based deSolve (similar package) allow convenient accurate solutions differential equations without leave macpan2. Third, TODO: describe model specification language can used build models modularly (e.g. swap alternative state-updaters discussed also add model structures like age-groups spatial structure simple unstructured model)","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"engine-agnostic-model-specification-language","dir":"Articles","previous_headings":"","what":"Engine-Agnostic Model Specification Language","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"engine-specific-model-specification-languages","dir":"Articles","previous_headings":"","what":"Engine-Specific Model Specification Languages","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"general-dynamic-simulation-with-tmb","dir":"Articles","previous_headings":"","what":"General Dynamic Simulation with TMB","title":"Design Concepts","text":"One can define generic set update steps iterated produce dynamic simulation model TMB, can used generate model simulations. part package general, stable, flexible. also meets many modellers , ability write set transitions/state updates. convenient just like simulate , model library .","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"model-library","dir":"Articles","previous_headings":"","what":"Model Library","title":"Design Concepts","text":"TODO: Reuse tools older concept starter models Establish specification","code":"(\"starter_models\"  |> mp_tmb_library(\"sir\", package = \"macpan2\")  |> mp_simulator(time_steps = 10, outputs = \"I\")  |> mp_trajectory() ) ##    matrix time row col    value ## 1       I    1   0   0 1.098000 ## 2       I    2   0   0 1.205169 ## 3       I    3   0   0 1.322276 ## 4       I    4   0   0 1.450133 ## 5       I    5   0   0 1.589599 ## 6       I    6   0   0 1.741573 ## 7       I    7   0   0 1.906995 ## 8       I    8   0   0 2.086833 ## 9       I    9   0   0 2.282085 ## 10      I   10   0   0 2.493761"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"calibration","dir":"Articles","previous_headings":"","what":"Calibration","title":"Design Concepts","text":"build function, mp_calibrate, takes (1) object simulating model trajectories (2) information calibrating certain quantities model. second type information detailed following sections. output mp_calibrate another object simulating model trajectories contains new default parameter values given fits additional stochasticity resulting parameter estimation uncertainty. big question calibration want engine-agnostic DSL layer, just want make sense engines makes sense? think latter, otherwise making things difficult. can try wise making reusable calibration machinery across engines comes .","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"specifying-data-to-fit","dir":"Articles","previous_headings":"Calibration","what":"Specifying Data to Fit","title":"Design Concepts","text":"data frame (data frames) containing observed (possibly uneven) time series compare model simulations. form data frame take? One option format output mp_trajectory. several benefits. Consistency input output formats, making little easier learn. Easy manipulate output input testing calibration functionality. Possibly simpler argument list mp_calibrate just relate observed data simulated data name, course still need interface distributional assumptions. Naturally handles missing values main disadvantage format differ indexed vectors discussed . disadvantage fixable way convert indexed vector lists ‘long-matrices’ format. Actually yes … totally fine. general design generic S3 method producing ‘long-matrices’ data frame.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"specifying-distributional-assumptions","dir":"Articles","previous_headings":"Calibration","what":"Specifying Distributional Assumptions","title":"Design Concepts","text":"Probably ways depending many different assumptions need made. one extreme every observation gets distribution, easily specified argument mp_calibrate. extreme observation gets distribution (including distributional parameters like spread shape), specified adding additional columns data frame observed values. Designs interfaces use cases somewhere two extremes seem less obvious.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"specifying-parameters-to-fit","dir":"Articles","previous_headings":"Calibration","what":"Specifying Parameters to Fit","title":"Design Concepts","text":"two kinds parameters fit. Existing quantities fitted (e.g. beta, initial number susceptible individuals S). Creating new quantities fitted (e.g. distributional scale parameters declared along distributional asumptions. scale (e.g. log, logit) fit parameters must also specified. new distributional parameters go new indexed vector called something like distributional_parameters. (TODO: general name new parameters part observation model, e.g. convolution kernel parameters).","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"alternative-trajectory-solvers","dir":"Articles","previous_headings":"","what":"Alternative Trajectory Solvers","title":"Design Concepts","text":"Let xx state vector bb vector per-capita flow rates. Let zz yy vectors states – zz (yy) vector length bb containing elements xx associated () state flow. Therefore, iith flow z[]z[] y[]y[] per-capita rate b[]b[]. way think single flow, xix_i state, xjx_j state, bkb_k per-capita flow rate. Inflow: xibkx_i b_k Outflow: xibkx_i b_k Inflow Outflow: $$","code":"outflow ~ group_sums(state * flow_rates, from, state)"},{"path":[]},{"path":[]},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"time-varying-parameters","dir":"Articles","previous_headings":"","what":"Time-Varying Parameters","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"vectors-in-the-tmb-engine","dir":"Articles","previous_headings":"","what":"Vectors in the TMB Engine","title":"Design Concepts","text":"TMB-engine-specific warm-model structure.","code":"state_labels = c(\"S\", \"I\", \"R\") flow = data.frame(     rate = c(\"infection\", \"recovery\")   , from = c(\"S\"        , \"I\"       )   , to   = c(\"I\"        , \"R\"       ) ) sir = mp_tmb_model_spec(     before = list(         state[S] ~ N - 1       , state[I] ~ 1       , state[R] ~ 0     )   , during = list(         flow_rate[infection] ~ beta * state[S] * state[I] / N       , flow_rate[recovery] ~ gamma * state[I]       , state ~ state + group_sums(flow_rate, to, state) - group_sums(flow_rate, from, state)   )   , default = list(       state     = mp_zero_vector(state_labels)     , flow_rate = mp_zero_vector(flow$rate)     , N = 100     , beta = 0.25     , gamma = 0.1   )   , integers = list(        from = mp_positions(flow$from, state_labels)      , to   = mp_positions(flow$to  , state_labels)   ) ) (sir   |> mp_simulator(time_steps = 10, outputs = \"I\")   |> mp_trajectory() ) ##    matrix time row col    value ## 1   state    1   I     1.147500 ## 2   state    2   I     1.316046 ## 3   state    3   I     1.508417 ## 4   state    4   I     1.727685 ## 5   state    5   I     1.977228 ## 6   state    6   I     2.260727 ## 7   state    7   I     2.582154 ## 8   state    8   I     2.945748 ## 9   state    9   I     3.355960 ## 10  state   10   I     3.817384"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"model-structure-and-bookkeeping","dir":"Articles","previous_headings":"","what":"Model Structure and Bookkeeping","title":"Design Concepts","text":"Structured models combinations simpler modular model components. example one might combine SIR model age-group contact model produce age structured model. modular model components called atomic models.","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"structure-in-expressions","dir":"Articles","previous_headings":"Model Structure and Bookkeeping","what":"Structure in Expressions","title":"Design Concepts","text":"Models composed expression lists. expression unstructured model can converted structured expression create structured model. example, following unstructured expression defines rate new infections emerge. symbol expression certain type within structured model, type determines gets translated structured expression. simplest structured model one collects S state vector elements S . interpretation S symbols, structured infection expression gets translated internally following. S become symbols extracting subsets state vector. case expression remains scalar expression two scalars obtained extracting subsets state vector. won’t take much imagination think examples multiple paths infection required, therefore single scalar-valued infection expression insufficient. vector-valued expression, example, model expanded state vector tracks geographic location S individuals. example, two patch model east west patch involve four-dimensional state vector following elements: S.east, S.west, .east, .west. case now two scalar-valued infection expressions. two patches fine write scalar-valued infection expressions, patches different types structure (e.g. age groups, symptom status, hospitalization, immunity status, etc …) become crucial software handles bookkeeping internally. see easy can , note two-patch infection expression can powerfully compactly expressed original unstructured expression, infection ~ beta * S * / N, S = c(state[S.east], state[S.west]) = c(state[.east], state[.west]). powerful? separates math dynamic mechanism, infection ~ beta * S * / N, bookkeeping required structured models mechanism applied different model strata. often modellers think. example, might location-structured SIR model need expand age- location-structured. case, infection still process, whereby susceptible individual contacts infectious individual create flow susceptible individuals infectious individuals. math applies strata model. boring necessary part connect math bookkeeping associated model structure, software focus making bookkeeping changes easy possible minimal changes required underlying mathematical expressions. Let’s look examples infection, watch bookkeeping get annoying. age-stratified model two age groups, now get four scalar-valued infection expressions form infection ~ beta * S * / N. first expression young individual infecting old individual, second old individual infecting young individual, etc … Things get worse two age groups two patches. still isn’t bad, just first four expressions east last four west. now let’s introduce two symptom status categories: mild severe. intense. names square brackets get much less clear several ways model gets structured. lack clarity makes difficult see variety model assumptions looking scalar-valued expressions. infection beta vectors depend two age categories two symptom statuses, one location. young people can infect old people (vice versa), mildly infectious people can cause severe infection (vice versa), infectious people east infect people west (vice versa). labels associated two ages, first age mean, relative second age? discover need know look ages associated S states, can see first age category associated susceptible individual second infectious individual. related issue symptom status, expressed differently S individuals structured symptom status. case match second symptom status associated infection beta symptom status states, means first symptom status implicitly refers status newly infected individuals infectious individuals. Another way look last issue boxes play two different roles. first role individual infects S individual, second individual S individual becomes infected. None obvious scalar-valued expressions , difficult imagine clearer way explicitly write expression. approach bookkeeping different way. particular believe constructive approach structure provides comprehensible description, describe next. brief, believe grammar specifying steps associated adding structure can clearer description final structured model.","code":"infection ~ beta * S * I / N infection ~ beta * state[S] * state[I] / N infection[east] ~ beta * state[S.east] * state[I.east] / N infection[west] ~ beta * state[S.west] * state[I.west] / N infection[young.young] ~ beta[young.young] * state[S.young] * state[I.young] / N[young] infection[young.old]   ~ beta[young.old]   * state[S.young] * state[I.old]   / N[old] infection[old.young]   ~ beta[old.young]   * state[S.old]   * state[I.young] / N[young] infection[old.old]     ~ beta[old.old]     * state[S.old]   * state[I.old]   / N[old] infection[young.young.east] ~ beta[young.young.east] * state[S.young.east] * state[I.young.east] / N[young.east] infection[young.old.east]   ~ beta[young.old.east]   * state[S.young.east] * state[I.old.east]   / N[old.east] infection[old.young.east]   ~ beta[old.young.east]   * state[S.old.east]   * state[I.young.east] / N[young.east] infection[old.old.east]     ~ beta[old.old.east]     * state[S.old.east]   * state[I.old.east]   / N[old.east] infection[young.young.west] ~ beta[young.young.west] * state[S.young.west] * state[I.young.west] / N[young.west] infection[young.old.west]   ~ beta[young.old.west]   * state[S.young.west] * state[I.old.west]   / N[old.west] infection[old.young.west]   ~ beta[old.young.west]   * state[S.old.west]   * state[I.young.west] / N[young.west] infection[old.old.west]     ~ beta[old.old.west]     * state[S.old.west]   * state[I.old.west]   / N[old.west] infection[young.young.east.mild.mild]     ~ beta[young.young.east.mild.mild]     * state[S.young.east] * state[I.young.east.mild]   / N[young.east] infection[young.young.east.mild.severe]   ~ beta[young.young.east.mild.severe]   * state[S.young.east] * state[I.young.east.severe] / N[young.east] infection[young.young.east.severe.mild]   ~ beta[young.young.east.severe.mild]   * state[S.young.east] * state[I.young.east.mild]   / N[young.east] infection[young.young.east.severe.severe] ~ beta[young.young.east.severe.severe] * state[S.young.east] * state[I.young.east.severe] / N[young.east] infection[young.old.east.mild.mild]       ~ beta[young.old.east.mild.mild]       * state[S.young.east] * state[I.old.east.mild]     / N[old.east] infection[young.old.east.mild.severe]     ~ beta[young.old.east.mild.severe]     * state[S.young.east] * state[I.old.east.severe]   / N[old.east] infection[young.old.east.severe.mild]     ~ beta[young.old.east.severe.mild]     * state[S.young.east] * state[I.old.east.mild]     / N[old.east] infection[young.old.east.severe.severe]   ~ beta[young.old.east.severe.severe]   * state[S.young.east] * state[I.old.east.severe]   / N[old.east] infection[old.young.east.mild.mild]       ~ beta[old.young.east.mild.mild]       * state[S.old.east]   * state[I.young.east.mild]   / N[young.east] infection[old.young.east.mild.severe]     ~ beta[old.young.east.mild.severe]     * state[S.old.east]   * state[I.young.east.severe] / N[young.east] infection[old.young.east.severe.mild]     ~ beta[old.young.east.severe.mild]     * state[S.old.east]   * state[I.young.east.mild]   / N[young.east] infection[old.young.east.severe.severe]   ~ beta[old.young.east.severe.severe]   * state[S.old.east]   * state[I.young.east.severe] / N[young.east] infection[old.old.east.mild.mild]         ~ beta[old.old.east.mild.mild]         * state[S.old.east]   * state[I.old.east.mild]     / N[old.east] infection[old.old.east.mild.severe]       ~ beta[old.old.east.mild.severe]       * state[S.old.east]   * state[I.old.east.severe]   / N[old.east] infection[old.old.east.severe.mild]       ~ beta[old.old.east.severe.mild]       * state[S.old.east]   * state[I.old.east.mild]     / N[old.east] infection[old.old.east.severe.severe]     ~ beta[old.old.east.severe.severe]     * state[S.old.east]   * state[I.old.east.severe]   / N[old.east] infection[young.young.west.mild.mild]     ~ beta[young.young.west.mild.mild]     * state[S.young.west] * state[I.young.west.mild]   / N[young.west] infection[young.young.west.mild.severe]   ~ beta[young.young.west.mild.severe]   * state[S.young.west] * state[I.young.west.severe] / N[young.west] infection[young.young.west.severe.mild]   ~ beta[young.young.west.severe.mild]   * state[S.young.west] * state[I.young.west.mild]   / N[young.west] infection[young.young.west.severe.severe] ~ beta[young.young.west.severe.severe] * state[S.young.west] * state[I.young.west.severe] / N[young.west] infection[young.old.west.mild.mild]       ~ beta[young.old.west.mild.mild]       * state[S.young.west] * state[I.old.west.mild]     / N[old.west] infection[young.old.west.mild.severe]     ~ beta[young.old.west.mild.severe]     * state[S.young.west] * state[I.old.west.severe]   / N[old.west] infection[young.old.west.severe.mild]     ~ beta[young.old.west.severe.mild]     * state[S.young.west] * state[I.old.west.mild]     / N[old.west] infection[young.old.west.severe.severe]   ~ beta[young.old.west.severe.severe]   * state[S.young.west] * state[I.old.west.severe]   / N[old.west] infection[old.young.west.mild.mild]       ~ beta[old.young.west.mild.mild]       * state[S.old.west]   * state[I.young.west.mild]   / N[young.west] infection[old.young.west.mild.severe]     ~ beta[old.young.west.mild.severe]     * state[S.old.west]   * state[I.young.west.severe] / N[young.west] infection[old.young.west.severe.mild]     ~ beta[old.young.west.severe.mild]     * state[S.old.west]   * state[I.young.west.mild]   / N[young.west] infection[old.young.west.severe.severe]   ~ beta[old.young.west.severe.severe]   * state[S.old.west]   * state[I.young.west.severe] / N[young.west] infection[old.old.west.mild.mild]         ~ beta[old.old.west.mild.mild]         * state[S.old.west]   * state[I.old.west.mild]     / N[old.west] infection[old.old.west.mild.severe]       ~ beta[old.old.west.mild.severe]       * state[S.old.west]   * state[I.old.west.severe]   / N[old.west] infection[old.old.west.severe.mild]       ~ beta[old.old.west.severe.mild]       * state[S.old.west]   * state[I.old.west.mild]     / N[old.west] infection[old.old.west.severe.severe]     ~ beta[old.old.west.severe.severe]     * state[S.old.west]   * state[I.old.west.severe]   / N[old.west]"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"constructive-descriptions-of-model-structure","dir":"Articles","previous_headings":"Model Structure and Bookkeeping","what":"Constructive Descriptions of Model Structure","title":"Design Concepts","text":"first step constructive better representation structured vectors. used dot-concatenation represent model strata. example, two-patch SI model epidemiological status geographic location state variable names: S.east, S.west, .east, .west. state vector gets structured becomes convenient describe variables using index table, rows describe state variable. representation can get subsets state vector represent epidemiological status.","code":"state = mp_cartesian(   mp_index(Epi = c(\"S\", \"I\")),   mp_index(Loc = c(\"east\", \"west\")) ) state ##  Epi  Loc ##    S east ##    I east ##    S west ##    I west beta = mp_group(state, \"Epi\") mp_subset(state, Epi = \"S\") ##  Epi  Loc ##    S east ##    S west mp_subset(state, Epi = \"I\") ##  Epi  Loc ##    I east ##    I west"},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"structured-vectors","dir":"Articles","previous_headings":"Model Structure and Bookkeeping","what":"Structured Vectors","title":"Design Concepts","text":"column vectors, rows ","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"alternative-engines","dir":"Articles","previous_headings":"","what":"Alternative Engines","title":"Design Concepts","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/design_concepts.html","id":"combining-expression-lists","dir":"Articles","previous_headings":"","what":"Combining Expression Lists","title":"Design Concepts","text":"expression lists really just lists expressions, can combined lists normally combined. example keep dynamics si model separate -reporting reporting delay corrections raw prevalence (TODO: really use incidence).","code":"library(macpan2) si_dynamics = list(     transition_rate = infection ~ beta * S * I / N   , state_update = S ~ S - infection   , state_update = I ~ I + infection ) reporting_correction = list(   post_processing = reports ~ convolution(I, c(0.5, 0.25, 0.25)) ) si = mp_dynamic_model(   expr_list = macpan2:::ExprList(during = c(si_dynamics, reporting_correction)),   unstruc_mats = list(S = 99, I = 1, beta = 0.25, N = 100) ) (si   |> mp_dynamic_simulator(time_steps = 10     , mats_to_return = \"reports\"     , mats_to_save = c(\"I\", \"reports\")   )   |> mp_trajectory() ) ##     matrix time row col    value ## 1  reports    1   0   0 0.873750 ## 2  reports    2   0   0 1.339617 ## 3  reports    3   0   0 1.669899 ## 4  reports    4   0   0 2.080193 ## 5  reports    5   0   0 2.589100 ## 6  reports    6   0   0 3.219119 ## 7  reports    7   0   0 3.997230 ## 8  reports    8   0   0 4.955432 ## 9  reports    9   0   0 6.131141 ## 10 reports   10   0   0 7.567307"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"introduction","dir":"Articles","previous_headings":"","what":"Introduction","title":"Development Principles and Patterns","text":"macpan2 package uses standard S3 object-oriented framework R. objects macpan2 standard R environments, standard S3 class attributes. approach allows us integrate standard generic S3 methods (e.g. print, predict), retaining benefits programming styles common outside R data-code bundling passing reference. can get benefits without dependencies third-party packages R6 instead use standard R tools, unorthodox yet interesting (us) way.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"constructing-and-using-objects","dir":"Articles","previous_headings":"Basics of the macpan2 Object Oriented Framework","what":"Constructing and Using Objects","title":"Development Principles and Patterns","text":"understand macpan2, users developers need understand construct objects. Objects macpan2 S3 class attributes standard R environments additional restrictions. looking restrictions, illustrate basic idea example. macpan2 package comes set vignette(\"example_models\", package = \"macpan2\"). One simple example SIR model stored . path points directory following files. read one files using standard R methods, illustrate objects using CSVReader function. function returns object class CSVReader. get print S3 class object, vector three items. three items? standard S3 method inheritance. doesn’t make sense, doesn’t matter now. also saw item just R environment. later. important thing read function listed. function method, importantly standard S3 method. S3 method? guessed , cover . call methods, like read() method, following way. sir_flows_reader read CSV file configured read. syntax might look strange many R users, used something like . reason sir_reader$read() works without arguments path read stored sir_reader object. can see (almost) everything stored object using ls function. see , along read method, something else called file, just file path reader configured read. Object components like file component, methods, called fields. ’s basic idea use objects macpan2. ’s summary. Objects standard R environments Objects standard R S3 classes Objects fields methods Object methods functions can make use object components","code":"(sir_path = system.file(\"model_library\", \"sir_vax\", package = \"macpan2\")) #> [1] \"/home/runner/work/_temp/Library/macpan2/model_library/sir_vax\" list.files(sir_path) #> [1] \"derivations.json\"            \"flows.csv\"                   #> [3] \"README.md\"                   \"settings.json\"               #> [5] \"trans.csv\"                   \"transmission_dimensions.csv\" #> [7] \"transmission_matrices.csv\"   \"variables.csv\" sir_flows_reader = CSVReader(sir_path, \"flows.csv\") sir_flows_reader #> Classes 'CSVReader', 'Reader', 'Base' <environment: 0x562e5f28ef68>  #> read : function ()   #> read_base : function () class(sir_flows_reader) #> [1] \"CSVReader\" \"Reader\"    \"Base\" sir_flows_reader$read() #>      from      to        flow               type from_partition to_partition #> 1       S       I   infection         per_capita            Epi          Epi #> 2       I       R       gamma         per_capita            Epi          Epi #> 3 S.unvax   S.vax vaccination         per_capita        Epi.Vax      Epi.Vax #> 4       S S.unvax       birth  per_capita_inflow            Epi      Epi.Vax #> 5       I S.unvax       birth  per_capita_inflow            Epi      Epi.Vax #> 6       R S.unvax       birth  per_capita_inflow            Epi      Epi.Vax #> 7       S               death per_capita_outflow            Epi         Null #> 8       I               death per_capita_outflow            Epi         Null #> 9       R               death per_capita_outflow            Epi         Null #>   flow_partition from_to_partition from_flow_partition to_flow_partition #> 1            Epi               Vax                 Vax              Null #> 2            Epi               Vax                 Vax              Null #> 3            Vax                                                    Null #> 4            Epi                                                    Null #> 5            Epi                                                    Null #> 6            Epi                                                    Null #> 7            Epi              Null                                  Null #> 8            Epi              Null                                  Null #> 9            Epi              Null                                  Null read.csv(file.path(sir_path, \"flows.csv\")) #>       from       to         flow                type  from_partition #> 1 S        I        infection    per_capita          Epi             #> 2 I        R        gamma        per_capita          Epi             #> 3 S.unvax  S.vax    vaccination  per_capita          Epi.Vax         #> 4 S        S.unvax  birth        per_capita_inflow   Epi             #> 5 I        S.unvax  birth        per_capita_inflow   Epi             #> 6 R        S.unvax  birth        per_capita_inflow   Epi             #> 7 S                 death        per_capita_outflow  Epi             #> 8 I                 death        per_capita_outflow  Epi             #> 9 R                 death        per_capita_outflow  Epi             #>    to_partition  flow_partition  from_to_partition  from_flow_partition #> 1 Epi           Epi             Vax                Vax                  #> 2 Epi           Epi             Vax                Vax                  #> 3 Epi.Vax       Vax                                                     #> 4 Epi.Vax       Epi                                                     #> 5 Epi.Vax       Epi                                                     #> 6 Epi.Vax       Epi                                                     #> 7 Null          Epi             Null                                    #> 8 Null          Epi             Null                                    #> 9 Null          Epi             Null                                    #>   to_flow_partition #> 1              Null #> 2              Null #> 3              Null #> 4              Null #> 5              Null #> 6              Null #> 7              Null #> 8              Null #> 9              Null ls(sir_flows_reader) #> [1] \"file\"      \"read\"      \"read_base\" sir_flows_reader$file #> [1] \"/home/runner/work/_temp/Library/macpan2/model_library/sir_vax/flows.csv\""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"defining-classes","dir":"Articles","previous_headings":"Basics of the macpan2 Object Oriented Framework","what":"Defining Classes","title":"Development Principles and Patterns","text":"define class write function called constructor. aleady seen constructor – CSVReader function . Let’s make . Let’s make class can generate sequences numbers. warm create class nothing contains nothing, illustrates basic boilerplate code creating class. first line constructor uses Base function create environment called self. second line sets selfs S3 class DoesNothing returns newly created S3 object. make class interesting store integer field. looks identical first version, now stored value n. Finally add method can something, change name describe can . Notice fields methods stored self (e.g. self$n) can used methods using $ operator extract value field method self. technical reason works self environment environment every method self environment. fact, self environment thing environment method. seems mind-bending, don’t worry . basics class definitions. ’s summary. Class definitions functions constructing objects class first thing class definition create self environment last thing class definition return self environment S3 object middle class definition one adds methods fields self environment self environment thing environments methods self (don’t worry )","code":"DoesNothing = function() {   self = Base()   return_object(self, \"DoesNothing\") } does_nothing = DoesNothing() does_nothing #> Classes 'DoesNothing', 'Base' <environment: 0x562e608270f8> DoesNothing = function(n) {   self = Base()   self$n = n  ## save value of the argument in the object   return_object(self, \"DoesNothing\") } does_nothing = DoesNothing(10) does_nothing #> Classes 'DoesNothing', 'Base' <environment: 0x562e60aa5690> does_nothing$n == 10 #> [1] TRUE SimpleSequence = function(n) {   self = Base()   self$n = n   self$generate = function() seq_len(self$n)   return_object(self, \"SimpleSequence\") } simple_sequence = SimpleSequence(10) simple_sequence$generate() #>  [1]  1  2  3  4  5  6  7  8  9 10"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"objects","dir":"Articles","previous_headings":"Details","what":"Objects","title":"Development Principles and Patterns","text":"macpan2, objects standard R environments S3 class attribute. Therefore, object oriented style involves basic foundational R concepts: environments S3 classes. two types environments setup. first kind environment S3 class attribute environment every function environment ","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"class-definitions","dir":"Articles","previous_headings":"Details","what":"Class Definitions","title":"Development Principles and Patterns","text":"Developers can define class defining standard R function returns instance class. talked bit technical details shouldn’t worry basics defining classes. one technicality worry . Objects created constructor can used methods accessible self environment. example, following code fails. good forces specific method dependencies coming . worse code succeeded following way. ‘work’ now? doesn’t matter never problem just always refer self explicitly methods. particular, proper approach following.","code":"BadClass = function() {   self = Base()   x = 10   self$f = function() x^2   return_object(self, \"BadClass\") } try(BadClass()$f()) #> Error in BadClass()$f() : object 'x' not found x = 10 BadClass()$f() #> [1] 100 GoodClass = function() {   self = Base()   self$x = 10   self$f = function() self$x^2   return_object(self, \"GoodClass\") } GoodClass()$f() #> [1] 100"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"principles","dir":"Articles","previous_headings":"","what":"Principles","title":"Development Principles and Patterns","text":"trade-offs among principles, good guidelines.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"small-classes","dir":"Articles","previous_headings":"Principles","what":"Small Classes","title":"Development Principles and Patterns","text":"able see whole constructor definition single screen – OK doesn’t happen though.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"avoid-modifying-well-tested-classes","dir":"Articles","previous_headings":"Principles","what":"Avoid Modifying Well-Tested Classes","title":"Development Principles and Patterns","text":"Extension better done introducing new classes, rather new methods. Big classes hard reason , test, stabilize.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"linear-inheritance","dir":"Articles","previous_headings":"Principles","what":"Linear Inheritance","title":"Development Principles and Patterns","text":"Classes inherit multiple parents.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"shallow-inheritance-hierarchy","dir":"Articles","previous_headings":"Principles","what":"Shallow Inheritance Hierarchy","title":"Development Principles and Patterns","text":"Parent classes may multiple children, cases hierarchy shallow simple. example, consider alternatives children inherit directly intermediate parent. things like start happen, usually best just extend intermediate parent can inherit directly Base class.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"balance-regeneration-with-consistency","dir":"Articles","previous_headings":"Principles","what":"Balance Regeneration with Consistency","title":"Development Principles and Patterns","text":"naive approach keeping components objects consistent regenerate object every change. continual regeneration can expensive. best avoid trade-much possible making fields cheap compute methods always recompute user asking . fields expensive regenerate therefore need stored regenerated necessary.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"patterns","dir":"Articles","previous_headings":"","what":"Patterns","title":"Development Principles and Patterns","text":"design patterns complying principles.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"alternative-classes","dir":"Articles","previous_headings":"Patterns","what":"Alternative Classes","title":"Development Principles and Patterns","text":"Alternative versions class set methods initial version. needs change becomes easy swap one alternative another. example, Reader() classes single method – $read() – without arguments. Therefore, bit functionality requires data read can modified simply writing new reader swapping old one, without needing modify code calls $read() method. methods alternative classes return type object, obviously return value can vary.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"argument-fields","dir":"Articles","previous_headings":"Patterns","what":"Argument Fields","title":"Development Principles and Patterns","text":"simplest kinds object components, essentially behave lists. Argument fields store arguments constructor. example object two argument fields. fields can accessed using standard $ [[ operators. Note although possible set fields, recommended. Rather one use $refresh() methods described .","code":"A = function(x, y) {   ...   self$x = x   self$y = y   ... } a = A(x = 10, y = 20) a$x == 10 ## TRUE a$y == 20 ## TRUE"},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"static-fields","dir":"Articles","previous_headings":"Patterns","what":"Static Fields","title":"Development Principles and Patterns","text":"Static fields store values derived arguments constructor. Static fields similar argument fields, contain derived quantities depend arguments rather arguments . simple example store sum two arguments static field. Note static fields may need updated $refresh() methods.","code":"A = function(x, y) {   ...   self$z = x + y   ... }"},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"standard-methods","dir":"Articles","previous_headings":"Patterns","what":"Standard Methods","title":"Development Principles and Patterns","text":"Standard methods compute return values derived arguments constructor. methods used cheap run, regeneration consistency balanced. pattern generally preferred option, simplest reason maintain directly ensures consistency.","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"composition","dir":"Articles","previous_headings":"Patterns","what":"Composition","title":"Development Principles and Patterns","text":"Objects can composed objects. Composition objects classes looks like . developers users can following. keeps classes small B can methods instead , small classes easier test stabilize. Testing can focus methods directly , can extended composing new classes like B.","code":"A = function(...) {   ...   self$b = B(self)   ... } ... B = function(a) {   ...   self$a = a   ... } a = A(...) a$b$method(...)"},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"refresh-methods","dir":"Articles","previous_headings":"Patterns","what":"Refresh Methods","title":"Development Principles and Patterns","text":"Methods refreshing fields shallow copies fields several composed objects … field gets edited, simplest thing ","code":""},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"private-methods","dir":"Articles","previous_headings":"Patterns","what":"Private Methods","title":"Development Principles and Patterns","text":"Private methods used methods class. nothing stoping developer user calling private method, guarantee private method consistent behaviour even exist. communicate privacy, private methods start dot following example shows.","code":"A = function(...) {   ...   self$.private = function(...) {...}   ...   self$public = function(...) {     ...     self.private(...)     ...   } }"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/development_patterns.html","id":"method-caching","dir":"Articles","previous_headings":"Patterns","what":"Method Caching","title":"Development Principles and Patterns","text":"Developers can manage performance costs computationally expensive methods method caching. developer calls cached method first time, computes result, stores cache, returns result. Subsequent method evaluations simply retrieve cached value, improving efficiency. Developers can ensure consistency invalidating cache whenever objects change, allowing balance cost regeneration need consistency.","code":"A = function(..., method_dependency, ...) {   ...   self$method_dependency = method_dependency   ...   self$expensive_method_1 = function() {     ...   }   ...   self$expensive_method_2 = function() {     ...   }   ...   self$cheap_method = function() {     ...   }   ...   self$modify_dependency = function(...) {     ...     self$cache$expensive_method_1$invalidate()     self$cache$expensive_method_2$invalidate()     ...   }   ...   initialize_cache(self, \"expensive_method_1\", \"expensive_method_2\")   ... }  a = A()  # takes time to return a$expensive_method()   # return immediately by returning the same value computed previously  # and stored in the cache a$expensive_method()  # change object and invalidate the cache to enforce consistency a$modify_dependency(...)  # again takes time to return, but the value is different because the # object was modified a$expensive_method()"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"the-problem","dir":"Articles","previous_headings":"","what":"The Problem","title":"Elementwise Binary Operators","text":"C++ engine every variable matrix. simple situation every variable matrix, elementwise binary operations can defined convenient properties. problem properties standard R, probably case numeric variables matrices. Differences standard R mathematical functions McMasterPandemic C++ engine make difficult test engine. document describes use R elementwise binary operators comparable engine. Consider following three related matrices. relate together x number rows, y number columns. Note although dimensionally related, three objects different shape x y one column row respectively, whereas one row column. relationships might naturally want multiply every column column vector x, R get following error. define rigorously convenient properties expect elementwise binary operators variables matrices, show convert elementwise binary operators R operators properties.","code":"A = matrix(rnorm(6), 3, 2)  # 3 by 2 matrix x = matrix(rnorm(3))        # 3 by 1 matrix y = t(rnorm(2))             # 1 by 2 matrix try(A * x) #> Error in A * x : non-conformable arrays"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"definition-of-an-elementwise-binary-operator-in-the-c-engine","dir":"Articles","previous_headings":"","what":"Definition of an Elementwise Binary Operator in the C++ Engine","title":"Elementwise Binary Operators","text":"Consider generic binary operator, ⊗\\otimes, operates two scalars produce third. can overload operator take two matrices, xx yy, return third matrix, zz. z=x⊗y z = x \\otimes y  elements zz given following expression. $$ z_{,j} = \\cases{ \\begin{array}{lll}   x_{,j} \\otimes y_{,j} & \\text{} n(x) = n(y) & \\text{} m(x) = m(y) & \\text{Standard Hadamard product} \\\\   x_{,j} \\otimes y_{,1} & \\text{} n(x) = n(y) & \\text{} m(y) = 1 & \\text{matrix column times column vector} \\\\   x_{,j} \\otimes y_{1,j} & \\text{} n(y) = 1 & \\text{} m(x) = m(y) & \\text{matrix row times row vector} \\\\   x_{,1} \\otimes y_{,j} & \\text{} n(x) = n(y) & \\text{} m(x) = 1 & \\text{Column vector times matrix column} \\\\   x_{1,j} \\otimes y_{,j} & \\text{} n(x) = 1 & \\text{} m(x) = m(y) & \\text{Row vector times matrix row} \\\\   x_{1,1} \\otimes y_{,j} & \\text{} n(x) = m(x) = 1  & & \\text{Scalar times matrix, vector scalar} \\\\   x_{,j} \\otimes y_{1,1} & \\text{} n(y) = m(y) = 1 & & \\text{Matrix, vector scalar times scalar} \\\\ \\end{array}} $$ functions n()n() m()m() give numbers rows columns respectively.","code":""},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"forcing-a-binary-operator-in-r-to-have-these-properties","dir":"Articles","previous_headings":"","what":"Forcing a Binary Operator in R to have these Properties","title":"Elementwise Binary Operators","text":"consider two matrix-valued operands, x y, standard binary operator, op (e.g. +), R.","code":""},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"step-1","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Step 1","title":"Elementwise Binary Operators","text":"operands shape just operation. works R numeric operations vectorized anyways.","code":"eq = dim(x) == dim(y) if (all(eq)) return(op(x, y))"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"step-2","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Step 2","title":"Elementwise Binary Operators","text":"x either one row one column, define operation arguments swapped otherwise keep operator unchanged.","code":"vec_x = any(dim(x) == 1L) op1 = op if (vec_x) op1 = function(x, y) op(y, x)"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"step-3","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Step 3","title":"Elementwise Binary Operators","text":"Apply base-R sweep function, making sure matrix-like operand comes first.","code":"if (any(eq) & vec_x) return(sweep(y, which(eq), x, op1)) if (any(eq))         return(sweep(x, which(eq), y, op1))"},{"path":"https://canmod.github.io/macpan2/articles/elementwise_binary_operators.html","id":"implementation-and-examples","dir":"Articles","previous_headings":"Forcing a Binary Operator in R to have these Properties","what":"Implementation and Examples","title":"Elementwise Binary Operators","text":"BinaryOperator constructor uses algorithm. examples. tried operations naively, R engine complain. Note algorithm right thing commutative (e.g. *) non-commutative (e.g. ^) operators.","code":"times = BinaryOperator(`*`) pow = BinaryOperator(`^`) (A = matrix(1:6, 3, 2)) #>      [,1] [,2] #> [1,]    1    4 #> [2,]    2    5 #> [3,]    3    6 (x = matrix(1:3, 3)) #>      [,1] #> [1,]    1 #> [2,]    2 #> [3,]    3 (y = matrix(1:2, 1)) #>      [,1] [,2] #> [1,]    1    2 times(A, x) #>      [,1] [,2] #> [1,]    1    4 #> [2,]    4   10 #> [3,]    9   18 pow(A, y) #>      [,1] [,2] #> [1,]    1   16 #> [2,]    2   25 #> [3,]    3   36 try(A * x) #> Error in A * x : non-conformable arrays try(A ^ y) #> Error in A^y : non-conformable arrays identical(times(A, x), times(x, A)) #> [1] TRUE identical(pow(A, x), pow(x, A)) #> [1] FALSE"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"amuse-bouche","dir":"Articles","previous_headings":"","what":"Amuse bouche: a structured SIR model","title":"Engine-Agnostic Model Specification Grammar","text":"key macpan2’s flexible model grammar use functional forms repeat kinds calculations across model structures. instance, consider SIR model two pathogen strains (without co-infections):  , SS, IxI_x, RR numbers individuals susceptible, infected strain xx (AA BB), recovered, respectively, N=S+IA+IB+RN= S + I_A + I_B + R total population size, βx\\beta_x transmission rate strain xx, γ\\gamma recovery rate infected individuals,1 λx=βx(Ix)/N\\lambda_x = \\beta_x (I_x)/N force infection strain xx. can cast model system difference equations, since iterate numerically simulation: St+1=−[βA(IA)t/N+βB(IB)t/N]St,(IA)t+1=−[βA(IA)t/N−γ(IA)t,(IB)t+1=−[βB(IB)t/N−γ(IB)t,Rt+1=−[γ(IA)t+γ(IB)t.\\begin{align} S_{t+1} & = - [\\beta_A (I_A)_t/N + \\beta_B (I_B)_t/N] S_t, \\\\  (I_A)_{t+1} &= \\phantom{-[} \\beta_A (I_A)_t/N - \\gamma (I_A)_t, \\\\  (I_B)_{t+1} &= \\phantom{-[} \\beta_B (I_B)_t/N - \\gamma (I_B)_t, \\\\  R_{t+1} &= \\phantom{-[}  \\gamma (I_A)_t + \\gamma (I_B)_t. \\end{align} force infection, λA=βA(IA)/N\\lambda_A = \\beta_A (I_A)/N λB=βB(IB)/N\\lambda_B = \\beta_B (I_B)/N functional form, , using expression like λ=βI/N\\lambda = \\beta / N. numerically simulating model, doesn’t take much effort write calculation separately something like: However, macpan2, can specify single functional form , instance attach ledger model object tabulates specific instances functional form used define component model. words, ledger enumerate specific subscripted lambda, beta, use time invoke associated functional form simulation. case, two calculations force infection ledger (one calculation per strain), one can easily imagine complicated case. instance, consider relatively simple two-city age-structured metapopulation model 10 age groups within two patches: 10x10x2 = 200 force infection terms form (one per combination age groups capture options susceptible infected interaction, repeated two patches). Using functional forms ledgers allows modeller focus modelling questions, like design model structure choice expressions forces infection, macpan2 handles bookkeeping, matching stratified variables calculating expressions. approach cuts rote repetition setting model calculations, turn reduces opportunity bugs simulation code. also means expanding model can simple updating calculation ledger, rather error-prone editing calculations simulation code. modeller write code cut repetition expanding simple model (many ), macpan2 provides ready-made model specification grammar enables easy model extension, especially building product models, can readily interface fast simulation calibration engines, like TMB.","code":"lambda.A = beta.A * I.A / N lambda.B = beta.B * I.B / N lambda = beta * I / N"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"appetizer-specifying-the-basic-sir-model","dir":"Articles","previous_headings":"","what":"Appetizer: specifying the basic SIR model","title":"Engine-Agnostic Model Specification Grammar","text":"Let’s start specifying basic SIR model, foundation two-strain model , macpan2: St+1=−βStIt/N,+1=−βStIt/N−γIt,Rt+1=−γIt.\\begin{align} S_{t+1} &= -\\beta S_t I_t/N, \\\\  I_{t+1} &= \\phantom{-} \\beta S_t I_t/N - \\gamma I_t, \\\\  R_{t+1} &=  \\phantom{-} \\gamma I_t. \\end{align} helpful set λ=βI/N\\lambda = \\beta /N recast equations : St+1=−λSt,+1=−λSt−γIt,Rt+1=−γIt.\\begin{align} S_{t+1} &= -\\lambda S_t, \\\\  I_{t+1} &=  \\phantom{-} \\lambda S_t - \\gamma I_t, \\\\  R_{t+1} &=  \\phantom{-} \\gamma I_t. \\end{align} Since focus quickstart guide macpan2’s model specification grammar, defined SIR_starter() function sweep details initializing model object rug (now, though revisit later). need know SIR_starter() stage pass inputs define model using model grammar output model object can build simulator. primary focus remainder vignette inputs SIR_starter() created. inputs SIR_starter() two types: index tables containing indices (labels) model quantities, ledgers tabulate specific calculations required simulate model equations (based included functional forms). index tables need specify fall two groups: state: state names, SS, II, RR model equations rate: rate names, β\\beta, γ\\gamma, derived rate λ\\lambda identified two useful functional forms baked SIR_starter(). case, ’re thinking forms necessarily repeated calculations particular model, calculations modeller may want repeat line, expand simple model additional structure (). forms : flow: Unsigned flows one class another form rXrX, r>0r>0 per capita flow rate XX occupancy state flow originates. calculation repeated terms right-hand side recast system difference equations . force infection: prevalence-dependent per capita rate flow susceptible classes infectious classes form λ=βI/N\\lambda = \\beta /N, used calculating infection flows. case, flow form repeated within model equations, force infection form used . ’ve identified force infection functional form since want repeat later expanding two-strain model. Either way, forms already baked SIR_starter(), task creating ledger forms input function. start creating state rate index tables: mp_index() function sets structures like data frames tabulate model quantity labels: Epi column name unimportant simple model, key stratifying model quantities different features (epidemiological status, infection type, age group, location) complicated models. flow form, create two ledgers: infection flow SS II recovery flow II RR pass list flow argument SIR_starter(). specify flows using name state originates (from_states), state goes (to_states), flow rate name (flow_rates). use mp_join() function create infection ledger like : mp_join() function takes options provided argument from_states, to_states, flow_rates, e.g. default creates one entry ledger combination values (.e., full join). However, since one value column, one entry resulting ledger: names arguments mp_join() function tied functional form baked SIR_starter() specified, general modellers can define functional forms corresponding mp_join() argument names however like.2 create recovery ledger similar way: Finally, force_of_infection ledger slightly different corresponds different functional form SIR_starter() (mp_join() argument names different): functional form, need specify transmission_rates infectious_states involved computing force infection, well names want store results calculation (infection_flow_rates) use infection flow calculations. Now can use SIR_starter() function initialize model object: can create model simulator using mp_dynamic_simulator()3, giving model object (model), initial values index (vectors), well number total time steps simulation (time_steps): Note ’ve specified NA lambda calculated us using force infection functional form. can actually simulate model passing model simulator mp_trajectory(): output simulation long data frame: simulation output several columns: matrix: matrix storing values internally, corresponding two index tables, state rate. time: internal time index, time = 1 result first step simulation loop. row: primary label value (row name corresponding matrix). col: secondary label value (column name corresponding matrix). Since outputs model (.e. states rates) specified vectors matrices, column empty entries. TODO: useful? value: numerical value. output can manipulated plotted standard tools, like dplyr ggplot2, e.g.:  (, used base R pipe operator, |>.) prefer make plots base R, can convert long format data wide format: can plot one state like  multiple states plot ","code":"## index tables to label model quantities ------------------------- state <- mp_index(Epi = c(\"S\", \"I\", \"R\")) rate <- mp_index(Epi = c(\"beta\", \"gamma\", \"lambda\")) state ##  Epi ##    S ##    I ##    R rate ##     Epi ##    beta ##   gamma ##  lambda ## infection ledger ------------------------- infection <- mp_join(   from_states = mp_subset(state, Epi = \"S\"),   to_states = mp_subset(state, Epi = \"I\"),    flow_rates = mp_subset(rate, Epi = \"lambda\") ) mp_subset(state, Epi = \"S\") ##  Epi ##    S mp_subset(state, Epi = \"I\") ##  Epi ##    I mp_subset(rate, Epi = \"lambda\") ##     Epi ##  lambda infection ##  from_states to_states flow_rates ##            S         I     lambda ## recovery ledger ------------------------- recovery  <- mp_join(   from_states = mp_subset(state, Epi = \"I\"),   to_states = mp_subset(state, Epi = \"R\"),   flow_rates = mp_subset(rate, Epi = \"gamma\") )  recovery ##  from_states to_states flow_rates ##            I         R      gamma ## force of infection ledger ------------------------- # infection additionally involves the calculation of a force of infection force_of_infection <- mp_join(   infectious_states = mp_subset(state, Epi = \"I\"),   transmission_rates = mp_subset(rate, Epi = \"beta\"),   infection_flow_rates = mp_subset(rate, Epi = \"lambda\") ) ## SIR model object ------------------------- sir <- SIR_starter(   # index tables   state = state,   rate = rate,   # ledgers   flow = list(     infection,     recovery   ),   force_of_infection = force_of_infection ) ## SIR model simulator ------------------------- sir_simulator <- mp_dynamic_simulator(   dynamic_model = sir,   vectors = list(     state = c(S = 999, I = 1, R = 0),     rate = c(beta = 0.25, gamma = 0.1)   ),   time_steps = 100 ) ## SIR model simulation results ------------------------- sir_results <- mp_trajectory(sir_simulator) head(sir_results) ##   matrix time    row col     value ## 1  state    1      S     998.75025 ## 2  state    1      I       1.14975 ## 3  state    1      R       0.10000 ## 4   rate    1   beta       0.25000 ## 5   rate    1  gamma       0.10000 ## 6   rate    1 lambda       0.00025 (sir_results   |> filter(matrix == \"state\") # keep just the state variables at each point in time   |> mutate(state = factor(row, levels = c(\"S\", \"I\", \"R\"))) # to enforce logical state ordering in legend   |> ggplot(aes(time, value, colour = state))   +  geom_line() ) sir_results_wide <- (sir_results     |> dplyr::filter(matrix == \"state\") # keep state variables at each point in time     ## drop unneeded columns before pivoting     |> dplyr::select(-c(matrix, col))     |> tidyr::pivot_wider(id_cols = time, names_from = row) )  head(sir_results_wide, n = 3) ## # A tibble: 3 × 4 ##    time     S     I     R ##   <int> <dbl> <dbl> <dbl> ## 1     1  999.  1.15 0.1   ## 2     2  998.  1.32 0.215 ## 3     3  998.  1.52 0.347 with(sir_results_wide,      plot(x = time,           y = I,           type = \"l\") ) par(las = 1) ## horizontal y-axis ticks matplot(sir_results_wide[, 1],         sir_results_wide[,-1],         type = \"l\",         xlab = \"time\", ylab = \"\") legend(\"left\", col = 1:3, lty = 1:3, legend = state$labels())"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"main-course","dir":"Articles","previous_headings":"","what":"Main course: expanding the basic SIR with additional structure","title":"Engine-Agnostic Model Specification Grammar","text":"previously noted, created force infection functional form (βI/N\\beta / N) despite used define SIR model. However, consider two-strain model , see calculation repeated strain: λA=βAIA/NλB=βBIB/N\\begin{align} \\lambda_A &= \\beta_A I_A/N \\\\  \\lambda_B &= \\beta_B I_B/N \\end{align} Since already form force infection, can easily expand basic SIR strain-related structure get two-strain SIR model. define two-strain model, must specify state rate index tables, well infection, recovery, force_of_infection ledgers. start creating new set indices strains: simple approach define table new state rate indices directly using mp_index() function, : However, approach less flexible want build complex model already simpler, working model (like SIR ) want expand many strata /several different types strata. present alternative approach verbose far flexible. state, want cross II different strains create one II compartment name per strain. can using mp_cartesian() function, takes Cartesian product indices (possible combinations across sets)4: table stores indices associated II compartment.5 combine newly-stratified II indices states remain unchanged using mp_union() function make state index table: update rate index table similarly: infection ledger, let’s see previous code generating yields now (partially) stratifying Strain: , default mp_join() give possible combinations indices (full join), individual indices, denoted values Epi Strain columns, dot-concatenated full quantity labels. model, want two flows: flow S .flow rate lambda.flow S .B flow rate lambda.B words, want Strain index match Strain index lambda. can specify within mp_join() building ledger like : Note syntax argument . list element correspond pairwise join two index tables passed mp_join(). indices involved join correspond dot concatenated list element name (to_states.flow_rates), names coming mp_join()’s argument names (to_states, flow_rates). list element value character string corresponding index table column name upon perform matches. case, value \"Strain\" want “state” labels “flow rate” labels match based Strain index table column (.lambda..B lambda.B). recovery ledger, haven’t stratified gamma R, default full join labels yields exactly flows want: force infection ledger, full join yields many combinations don’t want: want lambda, , beta labels matched Strain column respective index tables. Internally, mp_join() performs pairwise joins, specify three-way argument. Instead, specify two pairwise joins effect: Now ’re ready build two-strain model object simulate :","code":"Strain_indices <- c(\"A\", \"B\") state <- mp_index(   Epi = c(\"S\", rep(\"I\", 2), \"R\"),   Strain = c(\"\", Strain_indices, \"\") )  rate <- mp_index(   Epi = c(rep(c(\"beta\", \"lambda\"), 2), \"gamma\"),   Strain = c(rep(c(\"A\", \"B\"), each = 2), \"\") ) I_indices <- mp_cartesian(   mp_subset(state, Epi = \"I\"),   mp_index(Strain = Strain_indices) )  I_indices ##  Epi Strain ##    I      A ##    I      B state <- mp_union(   mp_subset(state, Epi = \"S\"),   I_indices,    mp_subset(state, Epi = \"R\") )  state ##  Epi Strain ##    S        ##    I      A ##    I      B ##    R rate <-    mp_union(   # stratify rates involved in the infection process by strain   mp_cartesian(     mp_subset(rate, Epi = c(\"beta\", \"lambda\")),     mp_index(Strain = Strain_indices)   ),   # recovery rate will be the same across strains   mp_subset(rate, Epi = \"gamma\") )  rate ##     Epi Strain ##    beta      A ##  lambda      A ##    beta      B ##  lambda      B ##   gamma # infection ledger from before mp_join(   from_states = mp_subset(state, Epi = \"S\"),   to_states = mp_subset(state, Epi = \"I\"),    flow_rates = mp_subset(rate, Epi = \"lambda\") ) ##  from_states to_states flow_rates ##           S.       I.A   lambda.A ##           S.       I.B   lambda.A ##           S.       I.A   lambda.B ##           S.       I.B   lambda.B ## new infection ledger ------------------------- infection <- mp_join(   from_states = mp_subset(state, Epi = \"S\"),   to_states = mp_subset(state, Epi = \"I\"),    flow_rates = mp_subset(rate, Epi = \"lambda\"),   by = list(     to_states.flow_rates = \"Strain\"   ) )  infection ##  from_states to_states flow_rates ##           S.       I.A   lambda.A ##           S.       I.B   lambda.B recovery <- mp_join(     from_states = mp_subset(state, Epi = \"I\"),     to_states = mp_subset(state, Epi = \"R\"),     flow_rates = mp_subset(rate, Epi = \"gamma\") ) recovery ##  from_states to_states flow_rates ##          I.A        R.     gamma. ##          I.B        R.     gamma. mp_join(   infection_flow_rates = mp_subset(rate, Epi = \"lambda\"),   infectious_states = mp_subset(state, Epi = \"I\"),   transmission_rates = mp_subset(rate, Epi = \"beta\") ) ##  infection_flow_rates infectious_states transmission_rates ##              lambda.A               I.A             beta.A ##              lambda.B               I.A             beta.A ##              lambda.A               I.B             beta.A ##              lambda.B               I.B             beta.A ##              lambda.A               I.A             beta.B ##              lambda.B               I.A             beta.B ##              lambda.A               I.B             beta.B ##              lambda.B               I.B             beta.B ## new force of infection ledger ------------------------- force_of_infection <- mp_join(   infection_flow_rates = mp_subset(rate, Epi = \"lambda\"),   infectious_states = mp_subset(state, Epi = \"I\"),   transmission_rates = mp_subset(rate, Epi = \"beta\"),   by = list(     infection_flow_rates.infectious_states = \"Strain\", # first pairwise join     infectious_states.transmission_rates = \"Strain\" # second pairwise join   ) )  force_of_infection ##  infection_flow_rates infectious_states transmission_rates ##              lambda.A               I.A             beta.A ##              lambda.B               I.B             beta.B two_strain_model <- SIR_starter(   # index tables   state = state,   rate = rate,   # ledgers   flow = list(     infection,     recovery   ),   force_of_infection = force_of_infection )  two_strain_simulator <- mp_dynamic_simulator(   dynamic_model = two_strain_model,   vectors = list(     state = c(S = 998, I.A = 1, I.B = 1, R = 0),     rate = c(beta.A = 0.25, gamma = 0.1, beta.B = 0.2)   ),   time_steps = 100 )  two_strain_results <- (mp_trajectory(two_strain_simulator)   |> filter(matrix == \"state\")                     )  levels <- unique(two_strain_results$row) # get state variables in the desired order  (two_strain_results # keep state variables at each point in time   |> mutate(state = factor(row, levels = levels)) # to enforce logical state ordering in plot   |> ggplot(aes(time, value, colour = state))   +  geom_line() )"},{"path":"https://canmod.github.io/macpan2/articles/engine_agnostic_grammar.html","id":"dessert","dir":"Articles","previous_headings":"","what":"Dessert: understanding model simulation in macpan2","title":"Engine-Agnostic Model Specification Grammar","text":"mentioned, ’ve hidden details initializing model object within SIR_starter() function: function definition shows pieces fit together. expressions list expr_list perhaps interesting contains functional forms used simulate model, including explored (unsigned flows, force infection), well didn’t discuss (total inflow, total outflow, state update). ledgers init_vecs just set ensure ledgers initial conditions simulation get attached model object correctly. topics discussed fully future vignette.","code":"## helper function to simplify the exposition in this vigette ----------- SIR_starter <- function(   # index tables for model quantities   state,   rate,   # ledgers tabulating the use of different functional forms   flow, # list of individual ledgers   force_of_infection ){      ## Set up expressions list for each functional form --------------   ## names refer to when the calculation gets performed relative to    ## the simulation time-step loop (before, during, ...)   ## FIXME: we should not be referring to a specific engine in   ## a vignette about an 'engine-agnostic grammar'   expr_list <- mp_tmb_expr_list(     before = list(       ## aggregations         N ~ sum(state)     ),     during = list(       ## force of infections         rate[infection_flow_rates] ~           state[infectious_states] * rate[transmission_rates] / N          ## unsigned individual flows       , flow_per_time ~ state[from_states] * rate[flow_rates]          ## state update       , total_inflow ~ group_sums(flow_per_time, to_states, state)       , total_outflow ~ group_sums(flow_per_time, from_states, state)       , state ~ state + total_inflow - total_outflow     )   )      ## Ledgers for each specific calculation --------------   ledgers <- list(     flow = mp_ledgers(flow),     force_of_infection = mp_ledgers(force_of_infection)   )      ## Initialize vectors from index tables (with all zeros for values) --------------   # used as placeholders for user input   init_vecs <- list(     state = mp_structured_vector(state),     rate = mp_structured_vector(rate)   )      ## Initialize model object -----------------   mp_dynamic_model(     expr_list = expr_list,     ledgers = ledgers,     init_vecs = init_vecs   ) }"},{"path":"https://canmod.github.io/macpan2/articles/example_models.html","id":"finding-example-models","dir":"Articles","previous_headings":"","what":"Finding Example Models","title":"Example Models","text":"macpan2 comes set example model definitions, can listed show_models function. three things can items list: read , use , modify . read , just click links take model. use modify , please continue reading.","code":"show_models()"},{"path":"https://canmod.github.io/macpan2/articles/example_models.html","id":"using-examples","dir":"Articles","previous_headings":"","what":"Using Examples","title":"Example Models","text":"use sir example can read R using following code. see actually generate simulations model see article. use another model, , replace sir another entry dir column .","code":"sir_dir = system.file(\"starter_models\", \"sir\", package = \"macpan2\") sir = mp_tmb_library(sir_dir) print(sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)"},{"path":"https://canmod.github.io/macpan2/articles/example_models.html","id":"modifying-examples","dir":"Articles","previous_headings":"","what":"Modifying Examples","title":"Example Models","text":"take sir jumping-point producing model one may use following code. running code can go files my_sir_dir modify see . Note typically want chose specific directory model instead using tempdir. still need read model usual way. look identical came , ’s just hasn’t modified … yet …","code":"my_sir_dir = file.path(tempdir(), \"my_sir\") mp_model_starter(\"sir\", my_sir_dir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) my_sir = mp_tmb_library(my_sir_dir) print(my_sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)"},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"calibration-defaults","dir":"Articles","previous_headings":"","what":"Calibration Defaults","title":"Specifying Likelihood and Prior Components","text":"calibration interface allows direct specification likelihood prior components. objective function calibration summation negative log likelihoods negative log prior densities. default, interface assumes poisson likelihoods uniform priors. demonstrated objective function calibration example. calibration output shows poisson likelihood used trajectory variable additional objective function terms indicate parameters beta R improper uniform prior density. Indicating prior information parameters.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"customizing-the-objective-function","dir":"Articles","previous_headings":"","what":"Customizing the Objective Function","title":"Specifying Likelihood and Prior Components","text":"specify likelihood /prior variable model can select distribution list available distributions,?macpan2::distribution.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"priors-on-model-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Priors on model parameters","title":"Specifying Likelihood and Prior Components","text":"Specifying priors usually done par argument mp_tmb_calibrator. example prior specification SHIVER model. parameter logit_p, logit transformed proportion p, given normal prior using distribution function macpan2::mp_normal two numeric inputs location standard deviation, sd. remaining parameters given improper uniform prior using macpan2::mp_uniform.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"likelihoods-on-model-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Likelihoods on model parameters","title":"Specifying Likelihood and Prior Components","text":"likelihood can specified trajectory variables calibration set-, identified traj argument mp_tmb_calibrator. SHIVER example, variables hospitalizations(H) reported_incidence specified negative binomial likelihood using macpan2::mp_neg_bin function. likelihoods location parameter set calibration machinery use simulated value trajectory location. dispersion parameter mp_neg_bin required.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"fixed-distributional-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Fixed distributional parameters","title":"Specifying Likelihood and Prior Components","text":"Distributional parameters parameters characterize distribution. Often location standard deviation. default, parameters assumed fixed fit. case previous [Prior Specification] example distributional parameters location sd specified numeric constants. Distributional parameters also assumed fixed set name existing variable model. Ex. mp_normal(sd = \"sd_var\")","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"fitting-distributional-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Fitting Distributional Parameters","title":"Specifying Likelihood and Prior Components","text":"Distributional parameters however, can fit calibration framework addition parameters using macpan2::mp_fit. See ?macpan2::fit_distr_params details. previous example [Likelihood Specification] shows negative binomial dispersion parameter fit mp_fit. numeric value provided dispersion starting value optimization routine. optimization, can see fitted dispersion distributional parameters coefficient table. default, named leading distr_params_ followed distributional parameter name corresponding model variable name.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"distributional-parameter-transformations","dir":"Articles","previous_headings":"Use Cases > Fitting Distributional Parameters","what":"Distributional Parameter Transformations","title":"Specifying Likelihood and Prior Components","text":"Distributional parameters default parameter transformations inherited respective distribution. See default_trans argument distribution (?macpan2::distribution). example, standard deviations definition strictly positive number, log transformation convenient use ensure condition met. Defaults can changed either passing distributional parameter transformation function ?macpan2::transform_distr_param trans_distr_param argument ?macpan2::fit_distr_params functions change single transformation. update transformations, named list transformations ?macpan2::transform_distr_param distributional parameter can given default_trans argument distribution.","code":""},{"path":"https://canmod.github.io/macpan2/articles/likelihood_prior_specs.html","id":"priors-on-distributional-parameters","dir":"Articles","previous_headings":"Use Cases","what":"Priors on distributional parameters","title":"Specifying Likelihood and Prior Components","text":"can specify priors distributional parameters : creating variable model distributional parameter referring distributional parameter name specifying prior focal parameter using distributional parameter name specify prior usual way","code":"spec = (   mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\")      ## 1. update the spec to include a new variable named 'my_var' to serve as   ## the standard deviation parameter for the Normal prior on 'beta'.   ## A numeric value of 0.1 is specified as the default for 'my_var', the    ## starting value in optimization.   |> mp_tmb_insert(default = list(my_var = 0.1)) ) ## generate data for calibration data = mp_simulator(spec, 50, \"infection\") |> mp_trajectory()  ## set-up calibrator cal = mp_tmb_calibrator(     spec   , data   , traj = \"infection\"     ## 2. We set a Normal prior on beta, and set the `sd` argument to 'my_var'     ## (would it ever make sense to use mp_fit for `sd` here?)   , par = list(beta = mp_normal(location = 0.35, sd = mp_nofit(\"my_var\"))       ## 3. setting a log-normal prior on 'my_var'     , my_var = mp_log_normal(1,1)    )   , default = list(beta = 0.25) )  ## we can see the prior density for both 'beta' and 'my_var' in the calibration ## objective function cal$simulator$tmb_model$obj_fn$obj_fn_expr #> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta,  #>     0.35, exp(my_var))) - sum(dnorm(log(my_var), 1, 1)) #> <environment: 0x5639e5f77088>  mp_optimize(cal) #> $par #>    params    params  #> 0.2000017 1.0015207  #>  #> $objective #> [1] 53.08736 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 9 #>  #> $evaluations #> function gradient  #>       10       10  #>  #> $message #> [1] \"relative convergence (4)\" mp_tmb_coef(cal) #>       term    mat row col default  type  estimate   std.error #> 1   params   beta   0   0    0.25 fixed 0.2000017 0.009166585 #> 2 params.1 my_var   0   0    0.10 fixed 1.0015207 0.707373865"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"hello-world","dir":"Articles","previous_headings":"","what":"Hello World","title":"Quickstart","text":"vignette shows simulate SI model, think simplest possible model epidemiological transmission. code defining SI model (see short article find example models). Simulating model requires choosing number time-steps run model outputs generate. Syntax simulating macpan2 models designed combine standard data prep plotting tools R, demonstrate following code.  (, used base R pipe operator, |>.) remainder article looks step required create plot detail, discusses alternative approaches.","code":"library(ggplot2) library(dplyr) library(tidyr) library(macpan2) si = mp_tmb_model_spec(     before = S ~ N - I   , during = mp_per_capita_flow(         from     = \"S\"            # compartment from which individuals flow       , to       = \"I\"            # compartment to which individuals flow       , rate     = \"beta * I / N\" # expression giving per-capita flow rate       , abs_rate = \"infection\"    # name of absolute flow rate = beta * I * S/N     )   , default = list(N = 100, I = 1, beta = 0.25) ) print(si) ## --------------------- ## Default values: ## --------------------- ##  matrix row col  value ##       N         100.00 ##       I           1.00 ##    beta           0.25 ##  ## --------------------- ## Before the simulation loop (t = 0): ## --------------------- ## 1: S ~ N - I ##  ## --------------------- ## At every iteration of the simulation loop (t = 1 to T): ## --------------------- ## 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  ##      abs_rate = \"infection\") library(ggplot2) library(dplyr) si_plot = (si    ## macpan2  |> mp_simulator(         time_steps = 50       , outputs = c(\"I\", \"infection\")     )  |> mp_trajectory()    ## dplyr  |> mutate(quantity = case_match(matrix       , \"I\" ~ \"Prevalence\"       , \"infection\" ~ \"Incidence\"     ))    ## ggplot2  |> ggplot()   + geom_line(aes(time, value))   + facet_wrap(~ quantity, scales = \"free\")  + theme_bw() ) print(si_plot)"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"creating-a-simulator","dir":"Articles","previous_headings":"","what":"Creating a Simulator","title":"Quickstart","text":"first step produce simulator object, can used generate simulation results. object can produced using mp_simulator function, takes following arguments. model : model specification object, si. time_steps: many time steps epidemic simulator run ? outputs : model variables return simulation output. default (optional) : Allows one update default parameter values initial conditions provided model specification (see argument default mp_tmb_model_spec function). variables specified default left values specification. si_simulator object contains information required generate model simulations infection 50 time steps, without actually generating simulations. interesting step simulation covered next section. moving explain separate step creating simulator step running simulations. reason two steps optimize performance computationally challenging applications software covered article. step creating simulator object computationally intensive next step actually generating simulations. Therefore separation useful single simulator can used repeatedly generate many different simulations. Three common examples requiring repeated simulations simulator : models stochasticity output different run, calibrating model parameters data using iterative optimization tools, running different scenarios updating certain parameters simulation. macpan2 primarily developed computationally challenging iterative simulation problems, believe better introduce two steps distinct beginning. Although two steps might seem unnecessarily complex within context article, keeping separate make life easier working realistic workflows models.","code":"si_simulator = mp_simulator(     model = si    , time_steps = 50   , outputs = c(\"I\", \"infection\") ) si_simulator ## --------------------- ## Before the simulation loop (t = 0): ## --------------------- ## 1: S ~ N - I ##  ## --------------------- ## At every iteration of the simulation loop (t = 1 to 50): ## --------------------- ## 1: infection ~ S * (beta * I/N) ## 2: S ~ S - infection ## 3: I ~ I + infection"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"generating-simulations","dir":"Articles","previous_headings":"","what":"Generating Simulations","title":"Quickstart","text":"Now simulation engine object, si_simulator, use generate simulation results using mp_trajectory() function. results come long (“narrow”) format, exactly one value per row: simulation results output data frame following columns: matrix: matrix value come ? variables represented matrices, although article consider 1--1 matrices. time: time index 1 time_steps. row, col: Placeholders variable components complicated structured models (covered article, useful example S different age groups geographic locations tracked separately). value: simulated value particular state time step.","code":"si_results = mp_trajectory(si_simulator) si_results |> head(8) ##      matrix time row col     value ## 1         I    1   0   0 1.2475000 ## 2 infection    1   0   0 0.2475000 ## 3         I    2   0   0 1.5554844 ## 4 infection    2   0   0 0.3079844 ## 5         I    3   0   0 1.9383066 ## 6 infection    3   0   0 0.3828223 ## 7         I    4   0   0 2.4134907 ## 8 infection    4   0   0 0.4751841"},{"path":"https://canmod.github.io/macpan2/articles/quickstart.html","id":"processing-results","dir":"Articles","previous_headings":"","what":"Processing Results","title":"Quickstart","text":"macpan2 provide data manipulation plotting tools (although macpan2helpers). philosophy focus engine modelling interface, provide outputs formats easy use data processing packages, like ggplot2, dplyr, tidyr, readily make use data long format. graphs example, required step renames model variables something makes sense graphical presentation. reproduce , take little care produce tidier dataset. rename state variable disease prevalence (number currently infected individuals). discrete-time model, can reinterpret infection incidence (number newly infected individuals) one time step. Note approach calculating incidence works time period incidence measured corresponds length one time step. assumption met – example time step one day incidence data reported every week – approaches computing incidence covered must taken. can generate ggplot dataset . want use base R plots, can convert long format data wide format using tidyr package.  ","code":"si_results = (si_results   |> mutate(matrix = case_match(matrix       , \"I\" ~ \"Prevalence\"       , \"infection\" ~ \"Incidence\"     ))   |> rename(quantity = matrix)   |> select(time, quantity, value) ) print(head(si_results, 8L)) ##   time   quantity     value ## 1    1 Prevalence 1.2475000 ## 2    1  Incidence 0.2475000 ## 3    2 Prevalence 1.5554844 ## 4    2  Incidence 0.3079844 ## 5    3 Prevalence 1.9383066 ## 6    3  Incidence 0.3828223 ## 7    4 Prevalence 2.4134907 ## 8    4  Incidence 0.4751841 library(tidyr) si_results_wide <- (si_results   |> tidyr::pivot_wider(       , id_cols = time       , names_from = quantity     )   |> rename(Time = time) ) head(si_results_wide, n = 3) ## # A tibble: 3 × 3 ##    Time Prevalence Incidence ##   <int>      <dbl>     <dbl> ## 1     1       1.25     0.248 ## 2     2       1.56     0.308 ## 3     3       1.94     0.383 with(si_results_wide,      plot(x = Time,           y = Incidence) ) par(las = 1) ## horizontal y-axis ticks matplot(     si_results_wide[, 1]   , si_results_wide[,-1]   , type = \"l\"   , xlab = \"Time\", ylab = \"\" ) legend(\"topleft\"   , col = 1:3   , lty = 1:3   , legend = c(\"Prevalence\", \"Incidence\") )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"setup","dir":"Articles","previous_headings":"","what":"Setup","title":"Fitting to Real Data","text":"usual need following packages. don’t , please get usual way (.e. using install.packages). addition, need iidda.api package. set options convenience.","code":"library(macpan2) library(dplyr) library(ggplot2) library(broom.mixed) if (!require(iidda.api)) {   repos = c(       \"https://canmod.r-universe.dev\"     , \"https://cran.r-project.org\"   )   install.packages(\"iidda.api\", repos = repos) } #> Warning in check_rapiclient(): Your installation of rapiclient does not support #> passing vectors to the arguments of iidda.api functions. If you wish to pass #> vectors, please follow installation instructions for rapiclient here: #> https://canmod.r-universe.dev/rapiclient api_hook = iidda.api::ops_staging options(iidda_api_msgs = FALSE, macpan2_verbose = FALSE)"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"one-scarlet-fever-outbreak-in-ontario","dir":"Articles","previous_headings":"","what":"One Scarlet Fever Outbreak in Ontario","title":"Fitting to Real Data","text":"following code pull data single scarlet fever outbreak Ontario ended 1930. data looks like.","code":"scarlet_fever_ontario = api_hook$filter(     resource_type = \"Compilation\"   , dataset_ids = \"canmod-cdi-harmonized\"   , iso_3166_2 = \"CA-ON\"  ## get ontario data   , time_scale = \"wk\"  ## weekly incidence data only    , disease = \"scarlet-fever\"      # get data between 1929-08-01 and 1930-10-01   , period_end_date = \"1929-08-01..1930-10-01\" ) print(scarlet_fever_ontario) #> # A tibble: 61 × 19 #>    basal_disease cases_this_period collection_year dataset_id    digitization_id #>    <chr>                     <dbl>           <dbl> <chr>         <chr>           #>  1 scarlet-fever                23            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  2 scarlet-fever                27            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  3 scarlet-fever                47            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  4 scarlet-fever                24            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  5 scarlet-fever                24            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  6 scarlet-fever                45            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  7 scarlet-fever                57            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  8 scarlet-fever                46            1929 canmod-cdi-h… cdi_sf_ca_1924… #>  9 scarlet-fever                45            1929 canmod-cdi-h… cdi_sf_ca_1924… #> 10 scarlet-fever                67            1929 canmod-cdi-h… cdi_sf_ca_1924… #> # ℹ 51 more rows #> # ℹ 14 more variables: disease <chr>, historical_disease <chr>, #> #   historical_disease_family <chr>, historical_disease_subclass <chr>, #> #   iso_3166 <chr>, iso_3166_2 <chr>, location <chr>, location_type <chr>, #> #   nesting_disease <chr>, original_dataset_id <chr>, period_end_date <date>, #> #   period_start_date <date>, scan_id <chr>, time_scale <chr> (scarlet_fever_ontario   |> ggplot(aes(period_end_date, cases_this_period))   + geom_line() + geom_point()   + ggtitle(\"Scarlet Fever Incidence in Ontario, Canada\")   + theme_bw() )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"sir-model","dir":"Articles","previous_headings":"","what":"SIR Model","title":"Fitting to Real Data","text":"begin pulling simple sir model model library.","code":"sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") print(sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"modify-model-for-reality","dir":"Articles","previous_headings":"","what":"Modify Model for Reality","title":"Fitting to Real Data","text":"take library model shelf need modify bit realistic. mp_tmb_insert() function, inserts new default values model expressions. first change population size population Ontario time. Second, SIR model assumes cases recorded data, realistic. therefore modify model include -reporting, creating case reports variable given product incidence (.e. weekly infection rate) reporting probability. can print modified model see changes made successfully.","code":"ontario_population = api_hook$filter(     resource_type = \"Compilation\"   , dataset_ids = \"canmod-pop-normalized\"   , iso_3166_2 = \"CA-ON\"  ## get ontario data      # get data between 1929-08-01 and 1930-10-01   , date = \"1929-08-01..1930-10-01\" ) sf_sir = mp_tmb_insert(sir   , default = list(N = median(ontario_population$population)) ) sf_sir = mp_tmb_insert(sf_sir     ## insert this expression ...   , expressions = list(reports ~ infection * report_prob)          ## at the end (i.e. Infinity) of the expressions evaluated     ## 'during' each iteration of the simulation loop ...   , at = Inf     , phase = \"during\"        ## add a new default value for the reporting probability   , default = list(report_prob = 1/300) ) print(sf_sir) #> --------------------- #> Default values: #> --------------------- #>       matrix row col        value #>         beta         2.000000e-01 #>        gamma         1.000000e-01 #>            N         3.393512e+06 #>            I         1.000000e+00 #>            R         0.000000e+00 #>  report_prob         3.333333e-03 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #> 3: reports ~ infection * report_prob"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"preparing-the-data","dir":"Articles","previous_headings":"","what":"Preparing the Data","title":"Fitting to Real Data","text":"first step preparing data macpan2 simulate model considering. simulate \"reports\" variable corresponds reported incidence (number new cases per time-step, case one week, multiplied reporting probability). next step get data format compatible format simulations. particular, need matrix, time, value columns. can omit row col columns, ‘matrices’ model 1--1 scalars.","code":"sir_simulator = mp_simulator(sf_sir   , time_steps = 5   , outputs = \"reports\" ) head(mp_trajectory(sir_simulator)) #>    matrix time row col        value #> 1 reports    1   0   0 0.0006666665 #> 2 reports    2   0   0 0.0007333330 #> 3 reports    3   0   0 0.0008066662 #> 4 reports    4   0   0 0.0008873327 #> 5 reports    5   0   0 0.0009760658 observed_data = (scarlet_fever_ontario   ## select the variables to be modelled -- a time-series of case reports.   |> select(period_end_date, cases_this_period)      ## change the column headings so that they match the columns   ## in the simulated trajectories.   |> mutate(matrix = \"reports\")   |> rename(value = cases_this_period)      ## create a `time` column with the time-step IDs that will correspond   ## to the time-steps in the simulation. this column heading also    ## must match the column with the time-steps in the simulated trajectories   |> mutate(time = seq_along(period_end_date)) ) print(head(observed_data)) #> # A tibble: 6 × 4 #>   period_end_date value matrix   time #>   <date>          <dbl> <chr>   <int> #> 1 1929-08-03         23 reports     1 #> 2 1929-08-10         27 reports     2 #> 3 1929-08-17         47 reports     3 #> 4 1929-08-24         24 reports     4 #> 5 1929-08-31         24 reports     5 #> 6 1929-09-07         45 reports     6"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"set-up-the-optimizer","dir":"Articles","previous_headings":"","what":"Set up the Optimizer","title":"Fitting to Real Data","text":"Now can create object can calibrated. assert fit beta, gamma, (initial value ) , report_prob. Note can choose fit parameters default list model spec. particular, default list model requires initial number infectious individuals, whereas S derived simulation loop S ~ N - - R.","code":"sir_cal = mp_tmb_calibrator(     spec = sf_sir   , data = observed_data      ## name the trajectory variable, with a name that   ## is the same in both the spec and the data   , traj = \"reports\"        ## fit the following parameters   , par = c(\"beta\", \"gamma\", \"I\", \"report_prob\") ) print(sf_sir) #> --------------------- #> Default values: #> --------------------- #>       matrix row col        value #>         beta         2.000000e-01 #>        gamma         1.000000e-01 #>            N         3.393512e+06 #>            I         1.000000e+00 #>            R         0.000000e+00 #>  report_prob         3.333333e-03 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #> 3: reports ~ infection * report_prob"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"run-the-optimization","dir":"Articles","previous_headings":"","what":"Run the Optimization","title":"Fitting to Real Data","text":"good start. warnings necessarily bad, might get us thinking.","code":"sir_opt = mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"examine-the-fit","dir":"Articles","previous_headings":"","what":"Examine the fit","title":"Fitting to Real Data","text":"OK, things great. convergence code 1, indicating model converge (convergence == 0 good). Examining parameter estimates, stored internally calibrator object, things get worse. doesn’t look right! high beta gamma values, confidence intervals enormous overlap zero. model fit doesn’t look bad.  going ? Can modify model /fitting procedure get reasonable parameter estimates reasonable trajectory?","code":"print(sir_opt) #> $par #>     params     params     params     params  #> 34.7694070 34.6536331  2.0572289  0.3480618  #>  #> $objective #> [1] 428.1971 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 143 #>  #> $evaluations #> function gradient  #>      200      144  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" mp_tmb_coef(sir_cal, conf.int = TRUE) #>       term         mat row col     default  type   estimate  std.error #> 1   params        beta   0   0 0.200000000 fixed 34.7694070 25.7158953 #> 2 params.1       gamma   0   0 0.100000000 fixed 34.6536331 25.7160472 #> 3 params.2           I   0   0 1.000000000 fixed  2.0572289  3.0405887 #> 4 params.3 report_prob   0   0 0.003333333 fixed  0.3480618  0.2575428 #>      conf.low  conf.high #> 1 -15.6328217 85.1716356 #> 2 -15.7488932 85.0561594 #> 3  -3.9022155  8.0166732 #> 4  -0.1567128  0.8528364 fitted_data = mp_trajectory_sd(sir_cal, conf.int = TRUE) (observed_data   |> ggplot()   + geom_point(aes(time, value))   + geom_line(aes(time, value)     , data = fitted_data   )   + geom_ribbon(aes(time, ymin = conf.low, ymax = conf.high)     , data = fitted_data     , alpha = 0.2     , colour = \"red\"   )   + theme_bw()   + facet_wrap(~matrix, ncol = 1, scales = \"free\") )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"fixing-the-optimization-problem","dir":"Articles","previous_headings":"","what":"Fixing the Optimization Problem","title":"Fitting to Real Data","text":"One way address lack convergence optimizer assess degree parameter estimates biologically reasonable. Take recovery rate, estimated gamma ~ 26.5 per time-step. Given time-step one week model, estimate implies individuals recover scarlet fever 1/26.5 weeks – much less day. quick search suggests recovery rate reasonable scarlet fever, rough guess infectious stage lasts one week much plausible 1/26.5 weeks. Now look transmission rate, beta. also estimated pretty large, interesting large standard errors beta gamma. standard errors suggest estimates precise. However, estimated correlation beta gamma close 1, suggesting many values parameters fit data well long similar magnitude. diagnosis, correct, suggests data sufficiently informative identify values beta gamma. Resolving identifiability issues often best done introducing prior information, rough guess gamma close 1. simplest way include prior information move gamma pars argument mp_tmb_calibrator default argument, . calibration specification try jointly fit beta gamma, rather fits beta assuming gamma = 1. warnings, now optimizer converges. standard errors coefficient table fixed effect correlations seem plausible. fit looks similar four-parameter model, consistent diagnosis non-identifiability.  Caution: Ben, paper always recommend careful prior information included without prior uncertainty? one (Elderd, Dukic, Dwyer 2006)","code":"mp_tmb_fixef_cov(sir_cal) |> cov2cor() #>                   beta      gamma          I report_prob #> beta         1.0000000  1.0000000 -0.9998561   0.9996857 #> gamma        1.0000000  1.0000000 -0.9998553   0.9996870 #> I           -0.9998561 -0.9998553  1.0000000  -0.9993009 #> report_prob  0.9996857  0.9996870 -0.9993009   1.0000000 sir_cal_assume_gamma = mp_tmb_calibrator(     spec = sf_sir   , data = observed_data      ## name the trajectory variable, with a name that   ## is the same in both the spec and the data   , traj = \"reports\"        ## fit the following parameters   , par = c(\"beta\", \"I\", \"report_prob\")   , default = list(gamma = 1) ) sir_opt_assume_gamma = mp_optimize(sir_cal_assume_gamma) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation print(sir_opt_assume_gamma) #> $par #>       params       params       params  #> 1.121602e+00 1.878305e+03 1.125689e-02  #>  #> $objective #> [1] 430.0021 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 79 #>  #> $evaluations #> function gradient  #>      131       80  #>  #> $message #> [1] \"relative convergence (4)\" mp_tmb_coef(sir_cal_assume_gamma) #>       term         mat row col     default  type     estimate    std.error #> 1   params        beta   0   0 0.200000000 fixed 1.121602e+00 1.801964e-03 #> 2 params.1           I   0   0 1.000000000 fixed 1.878305e+03 5.445606e+01 #> 3 params.2 report_prob   0   0 0.003333333 fixed 1.125689e-02 1.927763e-04 mp_tmb_fixef_cov(sir_cal_assume_gamma) |> cov2cor() #>                   beta          I report_prob #> beta         1.0000000 -0.7988821  -0.7608921 #> I           -0.7988821  1.0000000   0.5802420 #> report_prob -0.7608921  0.5802420   1.0000000 fitted_data = mp_trajectory_sd(sir_cal_assume_gamma, conf.int = TRUE) (observed_data   |> ggplot()   + geom_point(aes(time, value))   + geom_line(aes(time, value)     , data = fitted_data   )   + geom_ribbon(aes(time, ymin = conf.low, ymax = conf.high)     , data = fitted_data     , alpha = 0.2     , colour = \"red\"   )   + theme_bw()   + facet_wrap(~matrix, ncol = 1, scales = \"free\") )"},{"path":"https://canmod.github.io/macpan2/articles/real_data.html","id":"learning-the-functional-form-of-time-variation-in-transmission-new","dir":"Articles","previous_headings":"","what":"Learning the Functional form of Time Variation in Transmission (New!)","title":"Fitting to Real Data","text":"Let’s get bit data see two seasons.  Prepare fit data. make function can easily update dimension radial basis. also convenient make function plotting results Now try fitting number different dimensions.        Interestingly now managed fit gamma much slower recovery rate. Expected time R box one year! believeable, point make easier fit models can try things.","code":"scarlet_fever_ontario = api_hook$filter(     resource_type = \"Compilation\"   , dataset_ids = \"canmod-cdi-harmonized\"   , iso_3166_2 = \"CA-ON\"  ## get ontario data   , time_scale = \"wk\"  ## weekly incidence data only    , disease = \"scarlet-fever\"      # get data between 1929-08-01 and 1931-10-01   , period_end_date = \"1929-08-01..1931-10-01\"   ) (scarlet_fever_ontario   |> ggplot(aes(period_end_date, cases_this_period))   + geom_line() + geom_point()   + ggtitle(\"Scarlet Fever Incidence in Ontario, Canada\")   + theme_bw() ) observed_data = (scarlet_fever_ontario   ## select the variables to be modelled -- a time-series of case reports.   |> select(period_end_date, cases_this_period)      ## change the column headings so that they match the columns   ## in the simulated trajectories.   |> mutate(matrix = \"reports\")   |> rename(value = cases_this_period)      ## create a `time` column with the time-step IDs that will correspond   ## to the time-steps in the simulation. this column heading also    ## must match the column with the time-steps in the simulated trajectories   |> mutate(time = seq_along(period_end_date)) ) print(head(observed_data)) #> # A tibble: 6 × 4 #>   period_end_date value matrix   time #>   <date>          <dbl> <chr>   <int> #> 1 1929-08-03         23 reports     1 #> 2 1929-08-10         27 reports     2 #> 3 1929-08-17         47 reports     3 #> 4 1929-08-24         24 reports     4 #> 5 1929-08-31         24 reports     5 #> 6 1929-09-07         45 reports     6 make_rbf_calibrator = function(dimension) {   mp_tmb_calibrator(       spec = sf_sir     , data = observed_data     , traj = \"reports\"            ## -----------------------------     ## this is the key bit     , tv = mp_rbf(\"beta\", dimension)     ## -----------------------------          , par = c(\"gamma\", \"I\", \"report_prob\")   ) } plot_fit = function(cal_object) {   fitted_data = mp_trajectory_sd(cal_object, conf.int = TRUE)   (observed_data     |> ggplot()     + geom_point(aes(time, value))     + geom_line(aes(time, value)       , data = fitted_data       , colour = \"red\"     )     + geom_ribbon(aes(time, ymin = conf.low, ymax = conf.high)       , data = fitted_data       , alpha = 0.2       , colour = \"red\"     )     + theme_bw()   ) } sir_cal = make_rbf_calibrator(dimension = 1) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>       params       params       params       params       params  #>   1.07372447 365.34139607   0.21804031   0.09069968   0.86580386  #>  #> $objective #> [1] 2897.368 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 150 #>  #> $evaluations #> function gradient  #>      174      151  #>  #> $message #> [1] \"iteration limit reached without convergence (10)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 2) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>     params     params     params     params     params     params  #>  0.4662692 15.7705637  8.5178748 -0.5631177 -0.6997072  0.6673706  #>  #> $objective #> [1] 2977.803 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 150 #>  #> $evaluations #> function gradient  #>      200      150  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 3) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>        params        params        params        params        params  #>  7.480423e-01  7.126562e+03  5.678344e-03 -1.637587e-01 -2.970186e-02  #>        params        params  #>  9.244461e-01  6.246204e-01  #>  #> $objective #> [1] 1574.227 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 67 #>  #> $evaluations #> function gradient  #>       98       68  #>  #> $message #> [1] \"relative convergence (4)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 4) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>      params      params      params      params      params      params  #>  1.24671910 61.38245959  0.16124566  0.40605614 -0.11477326  0.33939236  #>      params      params  #> -0.07429845  0.61040344  #>  #> $objective #> [1] 1601.549 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 129 #>  #> $evaluations #> function gradient  #>      200      130  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 5) mp_optimize(sir_cal) #> $par #>       params       params       params       params       params       params  #> -0.003169677 50.290111756 30.026102089 -4.450364816  1.919450463 -6.177605279  #>       params       params       params  #>  1.776699439 -7.022692636  0.596297469  #>  #> $objective #> [1] 1433.989 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 122 #>  #> $evaluations #> function gradient  #>      200      122  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 6) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>     params     params     params     params     params     params     params  #>  0.7802570  7.7900568  5.2024837 -0.2791101  0.2589907 -0.5956717  0.3101396  #>     params     params     params  #> -0.3747950 -0.1376810  0.5863554  #>  #> $objective #> [1] 1441.466 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 128 #>  #> $evaluations #> function gradient  #>      200      128  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) sir_cal = make_rbf_calibrator(dimension = 7) mp_optimize(sir_cal) #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> $par #>      params      params      params      params      params      params  #>  0.02862238 13.83679544  6.50568272 -0.64364604 -1.38502686 -0.17206797  #>      params      params      params      params      params  #> -3.83455289 -0.06296071 -1.56407525 -3.70588098  0.58017538  #>  #> $objective #> [1] 1471.266 #>  #> $convergence #> [1] 1 #>  #> $iterations #> [1] 116 #>  #> $evaluations #> function gradient  #>      200      116  #>  #> $message #> [1] \"function evaluation limit reached without convergence (9)\" plot_fit(sir_cal) mp_tmb_coef(sir_cal) #>         term           mat row col     default  type    estimate   std.error #> 1     params         gamma   0   0 0.100000000 fixed  0.02862238  0.00652316 #> 2   params.1             I   0   0 1.000000000 fixed 13.83679544 19.17824368 #> 3  params.10 prior_sd_beta   0   0 1.000000000 fixed  0.58017538  0.01825558 #> 4   params.2   report_prob   0   0 0.003333333 fixed  6.50568272  9.02118967 #> 5   params.3 time_var_beta   0   0 0.000000000 fixed -0.64364604  0.18346250 #> 6   params.4 time_var_beta   1   0 0.000000000 fixed -1.38502686  0.14960302 #> 7   params.5 time_var_beta   2   0 0.000000000 fixed -0.17206797  0.11830797 #> 8   params.6 time_var_beta   3   0 0.000000000 fixed -3.83455289  0.13803399 #> 9   params.7 time_var_beta   4   0 0.000000000 fixed -0.06296071  0.16608048 #> 10  params.8 time_var_beta   5   0 0.000000000 fixed -1.56407525  0.10524492 #> 11  params.9 time_var_beta   6   0 0.000000000 fixed -3.70588098  0.24480729 mp_tmb_calibrator(     spec = sf_sir   , data = observed_data   , traj = \"reports\"     , tv = mp_rbf(\"beta\", dimension = 7)   , par = c(\"gamma\", \"I\", \"report_prob\")   , outputs = c(\"reports\", \"beta\") ) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #> 2: outputs_var_beta ~ group_sums(values_var_beta * time_var_beta[col_indexes_beta], row_indexes_beta, outputs_var_beta) #> 3: outputs_var_beta ~ c(outputs_var_beta[0], outputs_var_beta) #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: beta ~ exp(time_var(outputs_var_beta, data_time_indexes_beta)) #> 2: infection ~ S * (I * beta/N) #> 3: recovery ~ I * (gamma) #> 4: S ~ S - infection #> 5: I ~ I + infection - recovery #> 6: R ~ R + recovery #> 7: reports ~ infection * report_prob #>  #> --------------------- #> After the simulation loop (t = T + 1): #> --------------------- #> 1: sim_reports ~ rbind_time(reports, obs_times_reports) #>  #> --------------------- #> Objective function: #> --------------------- #> ~-sum(dpois(obs_reports, clamp(sim_reports))) - sum(dnorm(values_var_beta, 0, prior_sd_beta))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"decomposition-of-state-dependent-rates","dir":"Articles","previous_headings":"","what":"Decomposition of State-Dependent Rates","title":"State-Dependent Rates","text":"vast majority compartmental models contain flows depend states compartments directly involved flows. example, magnitude flow compartment compartment B depend another compartment, C. important example dependencies infection, use terminology infection processes. However, model subsume large number flows special cases. Let ss xx subsets state vector. length-nn vector ss contains -compartments – typically compartments susceptible infection – set flows. length-mm vector xx contains compartments – typically infectious compartments – affect flows. components xx need affect components yy need affect . Note keep track -compartments flows matter (think). define nn--mm transmission matrix following decomposition. T=diag(p)Bdiag(c) \\DeclareMathOperator{\\diag}{diag} T = \\diag(p) B \\diag(c) decomposition involves following terms. pp – length-nn vector susceptibilities ss state BB – nn--mm matrix contacts xx ss state cc – length-mm vector infectivities xx state alternative way write transmission matrix decomposition – prefer accurate representation actual computations – using element-wise operations. ∘\\circ element-wise product following. T=p∘B∘c⊤ T = p \\circ B \\circ c^\\top expression column vector pp element-wise multiplied column BB, row product element-wise multiplied row vector c⊤c^\\top, ⊤\\top matrix transpose operator. vector containing per-capita flow rates ss states following. λ=Tx \\lambda = Tx λ\\lambda vector often called force infection. finally absolute flow rates ss states following. r=λ∘s \\DeclareMathOperator{\\diag}{diag} r = \\lambda \\circ s","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir","dir":"Articles","previous_headings":"","what":"Example – SIR","title":"State-Dependent Rates","text":"ss vector contains single state, S, xx contains . case nn mm 1, components 1--1 follows. p=1p = 1 – susceptibility B=1B = 1 – contact matrix c=σNc = \\frac{\\sigma}{N} – infectivity Therefore following transmission matrix, per-capita flow rate vector, absolute flow rate vector. T=σNT = \\frac{\\sigma}{N} λ=σNI\\lambda = \\frac{\\sigma}{N} r=σNISr = \\frac{\\sigma}{N} overly simple hopefully clarifying example decided put σ\\sigma 1N\\frac{1}{N} components, pp, BB, cc. point somewhat mechanistic somewhat general decomposition transmission, start working complex models combining model modules (e.g. combining SEIR age spatial structure) way conveniently combine modules resulting transmission rates make mechanistic sense.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"product-models","dir":"Articles","previous_headings":"","what":"Product Models","title":"State-Dependent Rates","text":"Now consider two models, following triples representing transmission decomposition. (p1,B1,c1) (p_1, B_1, c_1) (p2,B2,c2) (p_2, B_2, c_2) Note subscripts represent model, components vectors matrices. dimensions two models n1,m1n_1, m_1 n2,m2n_2, m_2. Taking product two models results following triple. (p,B,c)=(p1⊗p2,B1⊗B2,c1⊗c2) (p, B, c) = (p_1\\otimes p_2, B_1\\otimes B_2, c_1\\otimes c_2) ⊗\\otimes Kronecker product. leads n1n2n_1n_2--1 column vector, pp, n1n2n_1n_2--m1m2m_1m_2 matrix, BB, m1m2m_1m_2--1 column vector cc. also x1,x2x_1, x_2 s1,s2s_1, s_2 combine xx ss. need make distinction factor models transmission without. example, SIR model clearly transmission, factor model just age groups . pure age model distinguish infectious susceptible people, process considers aging. Nevertheless age model becomes combined model transmission, want ready combined. make age model – factor model without transmission – ready combined model includes transmission need two things. First need account fact states may appear xx ss (e.g. young people can infectious susceptible). Second need include parameters used factor model’s processes used combined model includes transmission (e.g. age model needs contact matrix even though contact processes affect aging, process age model). next example illustrates ideas.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir-times-age","dir":"Articles","previous_headings":"","what":"Example – SIR times age","title":"State-Dependent Rates","text":"take product SIR model two-age-group factor model. components transmission decomposition particular age-group factor model follows. susceptibility: p=[11]p = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix} contact matrix: B=[q(1−q)(1−q)q]B = \\begin{bmatrix} q & (1 - q) \\\\ (1 - q) & q \\end{bmatrix} infectivity: c=[σyoungσyoung]c = \\begin{bmatrix} \\sigma_\\text{young} \\\\ \\sigma_\\text{young} \\end{bmatrix} qq probability given contact individuals age. symmetric contact matrix, didn’t need . also decided susceptibility depend age, absolutely parameterizing vector. little odd refer decomposition transmission, age-model contains aging processes include transmission. However, including transmission decomposition necessary prepare model combination model transmission. Taking product age model SIR model following transmission decomposition. susceptibility: p=[11]p = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix} contact matrix: B=[q(1−q)(1−q)q]B = \\begin{bmatrix} q & (1 - q) \\\\ (1 - q) & q \\end{bmatrix} infectivity: c=σN[σyoungσold]c = \\frac{\\sigma}{N}\\begin{bmatrix} \\sigma_\\text{young} \\\\ \\sigma_\\text{old} \\end{bmatrix} product model xx contains .young .old ss contains S.young S.old. transmission matrix can obtained multiplying three components decomposition follows. T=[11]∘[q(1−q)(1−q)q]∘σN[σyoungσold]=σN[qσyoung(1−q)σold(1−q)σyoungqσold] T = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix}  \\circ \\begin{bmatrix} q & (1 - q) \\\\ (1 - q) & q \\end{bmatrix}  \\circ \\frac{\\sigma}{N}\\begin{bmatrix} \\sigma_\\text{young} & \\sigma_\\text{old} \\end{bmatrix} = \\frac{\\sigma}{N} \\begin{bmatrix} q \\sigma_\\text{young} & (1 - q) \\sigma_\\text{old} \\\\ (1 - q) \\sigma_\\text{young} & q \\sigma_\\text{old} \\end{bmatrix} force infection vector product TT x=[IyoungIold]x = \\begin{bmatrix}I_{\\text{young}} \\\\ I_{\\text{old}}\\end{bmatrix} λ=σN[qσyoungIyoung+(1−q)σoldIold(1−q)σyoungIyoung+qσoldIold] \\lambda = \\frac{\\sigma}{N} \\begin{bmatrix} q \\sigma_\\text{young} I_{\\text{young}} + (1-q) \\sigma_\\text{old} I_{\\text{old}} \\\\ (1-q) \\sigma_\\text{young} I_{\\text{young}} + q \\sigma_\\text{old} I_{\\text{old}} \\end{bmatrix}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir-with-multiple-i-boxes-times-age","dir":"Articles","previous_headings":"","what":"Example – SIR with multiple I-boxes times age","title":"State-Dependent Rates","text":"example SIR model n=1n = 1 susceptible class m=2m = 2 infectious classes – mild severe – following transmission decomposition. susceptibility: p=1p = 1 contact matrix: B=[11]B = \\begin{bmatrix} 1 & 1 \\end{bmatrix} infectivity: c=1N[σmildσsevere]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\\\ \\sigma_\\text{severe} \\end{bmatrix} Multiplying decomposition age model (order) gives following model n=2n = 2 susceptible compartments m=4m = 4 infectious compartments. susceptibility: p=[11]p = \\begin{bmatrix} 1 \\\\ 1 \\end{bmatrix} contact matrix: B=[q(1−q)q(1−q)(1−q)q(1−q)q]B = \\begin{bmatrix} q & (1 - q) & q & (1 - q) \\\\ (1 - q) & q & (1 - q) & q \\end{bmatrix} infectivity: c=1N[σmildσyoungσmildσoldσsevereσyoungσsevereσold]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\sigma_\\text{young} \\\\ \\sigma_\\text{mild} \\sigma_\\text{old}\\\\ \\sigma_\\text{severe} \\sigma_\\text{young}\\\\ \\sigma_\\text{severe}\\sigma_\\text{old} \\end{bmatrix} non-square contact matrix might seem weird, fine modelling contacts two susceptible classes four infectious classes. One write 22--44 transmission matrix, don’t think informative. informative write component force infection vector, say young people. λyoung=1N(qσmildσyoungImild,young+(1−q)σmildσoldImild,old+qσsevereσyoungIsevere,young+(1−q)σsevereσoldIsevere,old) \\begin{array}{rrrrrrr} \\lambda_{\\text{young}} = \\frac{1}{N}  & ( & & q      \\sigma_\\text{mild}    \\sigma_\\text{young}  I_{\\text{mild},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{mild}    \\sigma_\\text{old}    I_{\\text{mild},\\text{old}} \\\\ & & + & q      \\sigma_\\text{severe}  \\sigma_\\text{young}  I_{\\text{severe},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{severe}  \\sigma_\\text{old}    I_{\\text{severe},\\text{old}} & ) \\\\ \\end{array} first term, example, gives contribution force infection due contacts young susceptible individuals mildly infected young individuals.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example-sir-with-multiple-i-boxes-and-partial-immunity-times-age","dir":"Articles","previous_headings":"","what":"Example – SIR with multiple I-boxes and partial immunity times age","title":"State-Dependent Rates","text":"starting approach ‘real’ models now. SIR model R box can now flow back , immunity gained infection recovery imperfect. model feature means ss vector two states, S R, n=2n = 2. xx vector contains I_mild I_severe, m=2m = 2 well. transmission decomposition looks like . susceptibility: p=[11−π]p = \\begin{bmatrix} 1 \\\\ 1 - \\pi \\end{bmatrix} contact matrix: B=[1111]B = \\begin{bmatrix} 1 & 1 \\\\ 1 & 1 \\end{bmatrix} infectivity: c=1N[σmildσsevere]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\\\ \\sigma_\\text{severe} \\end{bmatrix} π\\pi efficacy immunity reinfection. product model age looks like . susceptibility: p=[111−π1−π]p = \\begin{bmatrix} 1 \\\\ 1 \\\\ 1- \\pi \\\\ 1-\\pi \\end{bmatrix} contact matrix: B=[q(1−q)q(1−q)(1−q)q(1−q)qq(1−q)q(1−q)(1−q)q(1−q)q]B = \\begin{bmatrix} q & (1 - q) & q & (1 - q) \\\\ (1 - q) & q & (1 - q) & q  \\\\ q & (1 - q) & q & (1 - q) \\\\ (1 - q) & q & (1 - q) & q \\end{bmatrix} infectivity: c=1N[σmildσyoungσmildσoldσsevereσyoungσsevereσold]c = \\frac{1}{N}\\begin{bmatrix} \\sigma_\\text{mild} \\sigma_\\text{young} \\\\ \\sigma_\\text{mild} \\sigma_\\text{old}\\\\ \\sigma_\\text{severe} \\sigma_\\text{young}\\\\ \\sigma_\\text{severe}\\sigma_\\text{old} \\end{bmatrix} force infection young individuals R box, example, given following expression λR,young=1−πN(qσmildσyoungImild,young+(1−q)σmildσoldImild,old+qσsevereσyoungIsevere,young+(1−q)σsevereσoldIsevere,old) \\begin{array}{rrrrrr} \\lambda_{\\text{R,young}} = \\frac{1-\\pi}{N} & ( & & q      \\sigma_\\text{mild}    \\sigma_\\text{young}  I_{\\text{mild},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{mild}    \\sigma_\\text{old}    I_{\\text{mild},\\text{old}} \\\\ & & + & q      \\sigma_\\text{severe}  \\sigma_\\text{young}  I_{\\text{severe},\\text{young}} \\\\ & & + & (1-q)  \\sigma_\\text{severe}  \\sigma_\\text{old}    I_{\\text{severe},\\text{old}} & ) \\\\ \\end{array} Note almost identical expression λyoung\\lambda_\\text{young} , factor, 1−π1-\\pi, giving reduction transmission conferred immunity. λR,young=(1−π)λyoung \\lambda_{\\text{R,young}} = (1-\\pi) \\lambda_{\\text{young}}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"example","dir":"Articles","previous_headings":"","what":"Example","title":"State-Dependent Rates","text":"Assume SI model times young-old model. Variables.csv","code":"Epi,        Age S,          young I,          young S,          old I,          old susceptibility,   contact"},{"path":"https://canmod.github.io/macpan2/articles/state_dependent_rates.html","id":"bookkeeping-in-progress","dir":"Articles","previous_headings":"","what":"Bookkeeping (in progress)","title":"State-Dependent Rates","text":"Index element ss ii element xx jj. can define per-capita rate individuals flow sis_i compartment following decomposition. ri=piλi r_i = p_i \\lambda_i components decomposition follows. pip_i: susceptibility (e.g. complement vaccine efficacy) λi\\lambda_i: force infection definition, absolute rate flow sis_i given risir_i s_i. force infection . λi=∑jBijcjxj \\lambda_i = \\sum_j B_{ij}c_jx_j","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"branching-flows-and-process-error","dir":"Articles","previous_headings":"","what":"Branching Flows and Process Error","title":"ODE Solvers, Process Error, and Difference Equations","text":"","code":"siv = mp_tmb_model_spec(     before = list(S ~ N - I - V)   , during = list(         mp_per_capita_flow(\"S\", \"I\", infection ~ beta * I / N)       , mp_per_capita_flow(\"S\", \"V\", vaccination ~ rho)     )   , default = list(I = 1, V = 0, N = 100, beta = 0.25, rho = 0.1) ) print(siv) #> --------------------- #> Default values: #> --------------------- #>  matrix row col  value #>       I           1.00 #>       V           0.00 #>       N         100.00 #>    beta           0.25 #>     rho           0.10 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - V #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ beta *  #>      I/N) #> 2: mp_per_capita_flow(from = \"S\", to = \"V\", rate = vaccination ~  #>      rho) (siv   |> mp_euler_multinomial()  |> mp_simulator(50, \"infection\")  |> mp_trajectory()  |> ggplot()   + geom_line(aes(time, value)) )"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"internal-design","dir":"Articles","previous_headings":"","what":"Internal Design","title":"ODE Solvers, Process Error, and Difference Equations","text":"","code":"sir = mp_tmb_model_spec(   during = list(       N ~ S + I + R     , mp_per_capita_flow(\"S\", \"I\", \"beta * I / N\", \"infection\")     , mp_per_capita_flow(\"I\", \"R\", \"(1 - p) * gamma\", \"recovery\")     , mp_per_capita_flow(\"I\", \"D\", \"p * gamma\", \"death\")   ) )"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"changecomponent-classes","dir":"Articles","previous_headings":"Internal Design","what":"ChangeComponent() classes","title":"ODE Solvers, Process Error, and Difference Equations","text":"Model specs contain set three lists: * : instructions run simulation loop begins. * : instructions run iteration simulation loop. * : instructions run simulation loop ends. simplest way define lists using two-sided R formulas. list one may specify different types list components, class ChangeComponent. Internally, standard R formulas converted object class Formula, simplest kind ChangeComponent. Another important ChangeComponent PerCapitaFlow type, used standard flows one compartment another. list change components, just field ensuring elements valid ChangeComponent objects, can obtained using change_components() method model spec object. ChangeComponent objects must following methods.","code":"cc = sir$change_components() print(cc) #> [[1]] #> N ~ S + I + R #>  #> [[2]] #> From: S #> To: I #> Per-capita rate expression: beta * I/N #> Absolute rate symbol: infection #> [[3]] #> From: I #> To: R #> Per-capita rate expression: (1 - p) * gamma #> Absolute rate symbol: recovery #> [[4]] #> From: I #> To: D #> Per-capita rate expression: p * gamma #> Absolute rate symbol: death"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"the-change_frame-method","dir":"Articles","previous_headings":"Internal Design > ChangeComponent() classes","what":"The change_frame() method","title":"ODE Solvers, Process Error, and Difference Equations","text":"Returns data frame two columns: * state : state variable changed (.e. updated step) * change : signed absolute flow rates (variables expressions don’t involve state variables) example data frame flow S follows. simple Formula change component data frame just empty two-column data frame zero rows.","code":"cc[[2]]$change_frame() #>   state     change #> 1     S -infection #> 2     I +infection cc[[1]]$change_frame() #> [1] state  change #> <0 rows> (or 0-length row.names)"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"the-flow_frame-method","dir":"Articles","previous_headings":"Internal Design > ChangeComponent() classes","what":"The flow_frame() method","title":"ODE Solvers, Process Error, and Difference Equations","text":"Returns data frame three columns. * size : variable (often state variable function state variables) gives size population drawn flow (e.g. S size infection flow). * change : unsigned absolute flow rates. * rate : per-capita flow rates (variables expresions sometimes involve state variables). example data frame flow S follows. simple Formula change component data frame just empty three-column data frame zero rows.","code":"cc[[2]]$flow_frame() #>   size    change       rate         abs_rate #> 1    S infection beta * I/N S * (beta * I/N) cc[[1]]$flow_frame() #> [1] size     change   rate     abs_rate #> <0 rows> (or 0-length row.names)"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"changemodel-classes","dir":"Articles","previous_headings":"Internal Design","what":"ChangeModel() classes","title":"ODE Solvers, Process Error, and Difference Equations","text":"ChangeModel objects combine information lists ChangeComponent objects, specify full model. expands concept , , refined set steps. methods return lists two-sided formulas. before_loop() : list formulas. once_start() : Formulas evaluate start list, repeated (modified repeated) throughout expansions loop. example expansion Runge-Kutta differential equation solver reuses expressions iterative manner. Formulas returned once_during() useful specifying exogeneous changes (e.g., time-varying parameters) occur per time-step change throughout within-time-step iterations differential equation solver. before_flows() : Formulas evaluate absolute flow rates computed. update_flows() : Formulas update flows, using flow_frame() methods individual ChangeComponent objects. before_state() : Formulas evaluate state vector updated. update_state() : Formulas update state vector, using change_frame() method s individual ChangeComponent objects. after_state() : Formulas evaluate state vector updated. once_end() : Formulas evaluate end list, repeated throughout (similar once_start()). after_loop() : list formulas. ChangeModel objects also flow_frame() change_frame() methods combining outputs methods within individual ChangeComponent objects. example SIR model gives flow_frame() change_frame() output follows. update_flows() method update_state() method makes use flow_frame() produce ","code":"state   change -----   ------ S       -infection I       +infection I       -recovery R       +recovery size  change     rate ----  ------     ---- S     infection  beta * I / N I     recovery   gamma si = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") si$change_model #> Classes 'SimpleChangeModel', 'ChangeModelDefaults', 'ChangeModel', 'Base' <environment: 0x55a56aa1d908>  #> after_loop : function ()   #> after_state : function ()   #> all_user_aware_names : function ()   #> before_flows : function ()   #> before_loop : function ()   #> before_state : function ()   #> change_classes : function ()   #> change_frame : function ()   #> flow_frame : function ()   #> no_change_components : function ()   #> once_finish : function ()   #> once_start : function ()   #> other_generated_formulas : function ()   #> update_flows : function ()   #> update_state : function ()   #> user_formulas : function () si$change_model$flow_frame() #>   size    change       rate         abs_rate #> 1    S infection I * beta/N S * (I * beta/N) #> 2    I  recovery      gamma      I * (gamma) si$change_model$change_frame() #>   state     change #> 1     S -infection #> 2     I +infection #> 3     I  -recovery #> 4     R  +recovery si$change_model$update_state() #> [[1]] #> S ~ -infection #> <environment: 0x55a56a1dde20> #>  #> [[2]] #> I ~ +infection - recovery #> <environment: 0x55a56a1dde20> #>  #> [[3]] #> R ~ +recovery #> <environment: 0x55a56a1dde20> si$change_model$update_flows() #> $S #> $S[[1]] #> infection ~ I * beta/N #> <environment: 0x55a56a06efc0> #>  #>  #> $I #> $I[[1]] #> recovery ~ gamma #> <environment: 0x55a56a06efc0> spec = mp_tmb_model_spec(   during = list(       mp_per_capita_flow(\"A\", \"B\", \"a\", \"r\")     , mp_per_capita_flow(\"B\", \"C\", \"b\", \"rr\")   ) ) spec$change_model$update_flows() #> $A #> $A[[1]] #> r ~ a #> <environment: 0x55a569956fc0> #>  #>  #> $B #> $B[[1]] #> rr ~ b #> <environment: 0x55a569956fc0>"},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"updatemethod-classes","dir":"Articles","previous_headings":"Internal Design","what":"UpdateMethod() classes","title":"ODE Solvers, Process Error, and Difference Equations","text":"order define state updater one must define new UpdateMethod class. classes required update three methods take arguments: , , . methods required return list two-sided formulas giving expression list three phases simulation: simulation loop, every iteration simulation loop, simulation loop. Examples UpdateMethod classes include: EulerUpdateMethod, RK4UpdateMethod, EulerMultinomialUpdateMethod, HazardUpdateMethod. constructors UpdateMethod classes often field class ChangeModel, specifies sort components ","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"relationship-to-ordinary-differential-equation-solvers","dir":"Articles","previous_headings":"","what":"Relationship to Ordinary Differential Equation Solvers","title":"ODE Solvers, Process Error, and Difference Equations","text":"instructive view state update methods approximate solutions ordinary differential equations (ODEs). consider ODEs following form. dxidt=∑jxjrji⏟inflow−∑jxirij⏟outflow \\frac{dx_i}{dt} = \\underbrace{\\sum_j x_j r_{ji}}_{\\text{inflow}} - \\underbrace{\\sum_j x_i r_{ij}}_{\\text{outflow}}  per-capita rate flowing compartment ii compartment jj rijr_{ij}, xix_i number individuals iith compartment. allow rijr_{ij} depend number state variables time-varying parameters. example, SIR model xS,xI,xRx_S, x_I, x_R (readability use S,,RS, , R). case rSI=βI/Nr_{SI} = \\beta / N, rIR=γr_{IR} = \\gamma, values rijr_{ij} zero. force infection, rSIr_{SI}, depends state variable II. Although state-update method presented can thought approximate solution ODE, can also thought dynamical models right. example, Euler-multinomial model useful model process error.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"euler","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Euler","title":"ODE Solvers, Process Error, and Difference Equations","text":"simplest approach just pretend ODEs difference equations. case, time-step, state variable updated follows. xi=xi−∑jxirij+∑jxjrji x_i = x_i - \\sum_j x_i r_{ij} + \\sum_j x_j r_{ji}  SIR example follows. S=S−SrSI S = S - Sr_{SI} =−IrIR+SrSI = - Ir_{IR} + Sr_{SI} R=R+IrIR R = R + Ir_{IR}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"runge-kutta-4","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Runge Kutta 4","title":"ODE Solvers, Process Error, and Difference Equations","text":"TODO","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"euler-multinomial","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Euler-Multinomial","title":"ODE Solvers, Process Error, and Difference Equations","text":"Euler-multinomial state update method assumes number individuals move one box another single time-step random non-negative integer, coming particular multinomial distribution now describe. probability staying iith box entire time-step assumed following (TODO: relate Poisson processes). pii=exp(−∑jrij) p_{ii} = \\exp\\left(-\\sum_j r_{ij}\\right) probability assumes rijr_{ij} held constant throughout entire time-step, although can change time-step begins. probability moving box ii box jj one time-step given following. pij=(1−pii)rij∑jrij p_{ij} = (1 - p_{ii}) \\frac{r_{ij}}{\\sum_j r_{ij}} probability just probability staying box ii, 1−pii1 - p_{ii}, specifically going box jj, assumed given expression rij∑jrij\\frac{r_{ij}}{\\sum_j r_{ij}}. Let ρij\\rho_{ij} random number individuals move box ii box jj one time-step. expected value ρij\\rho_{ij} pijxip_{ij} x_i. However, random variables independent events, total number individuals, ∑ixi\\sum_i x_i, remain constant single time-step (least models currently considering). account non-independence, collect ρij\\rho_{ij} associated compartment ii vector ρi\\rho_i. collect similar vector probabilities, pip_i. ρi\\rho_i random draw multinomial distribution xix_i trials probability vector, pip_i. random draws made, state variables can updated time-step follows. xi=xi−∑jρij+∑jρji x_i = x_i - \\sum_j \\rho_{ij} + \\sum_j \\rho_{ji} Note actually need generate values diagonal elements, ρii\\rho_{ii}, cancel update equation. also can ignore ρij\\rho_{ij} rij=0r_{ij} = 0. SIR example particularly simple Euler-binomial distribution branching flows – individuals leave S can go leave can go R. two flows given following distributions. ρSI∼Binomial(S,pSI) \\rho_{SI} \\sim \\text{Binomial}(S, p_{SI}) ρIR∼Binomial(,pIR) \\rho_{IR} \\sim \\text{Binomial}(, p_{IR}) models branching flows multinomial distributions. model state update given following equations. S=S−ρSI S = S - \\rho_{SI} =−ρIR+ρSI = - \\rho_{IR} + \\rho_{SI} R=R+ρIR R = R + \\rho_{IR}","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"hazard","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Hazard","title":"ODE Solvers, Process Error, and Difference Equations","text":"Hazard update-method uses expected values associated Euler-multinomial described . particular, state variables updated follows. xi=xi−∑jxipij+∑jxjpji x_i = x_i - \\sum_j x_i p_{ij} + \\sum_j x_j p_{ji} SIR model follows. S=S−SpSI S = S - Sp_{SI} =−IpIR+SpSI = - Ip_{IR} + Sp_{SI} R=R+IpIR R = R + Ip_{IR} explicitly II compartment . (t+1)=(t)−(t)(1−exp(−γ))+S(t)(1−exp(−βI(t))) (t+1) = (t) - (t) (1 - \\exp(-\\gamma)) + S(t)(1 - \\exp(-\\beta (t)))","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"linearizing-at-each-time-step","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Linearizing at Each Time-Step","title":"ODE Solvers, Process Error, and Difference Equations","text":"rijr_{ij} depend state variable, ODE generally non-linear. However, linearize model every time-step explicitly compute matrix exponential find approximate state update.","code":""},{"path":"https://canmod.github.io/macpan2/articles/state_updaters.html","id":"hazard-in-models-including-more-than-unbalanced-per-capita-flows","dir":"Articles","previous_headings":"Relationship to Ordinary Differential Equation Solvers","what":"Hazard in models including more than unbalanced per-capita flows","title":"ODE Solvers, Process Error, and Difference Equations","text":"perfectly balanced per-capita flows approach used always work. example, virus shedding wastewater compartment involve infected individuals flowing wastewater compartment, people become wastewater obviously. models need think clearly use Hazard approximation. cases can modify differential equation include arbitrary number absolute inflows outflows. dxidt=∑jxjrji⏟inflow−∑jxirij⏟outflow+∑krik+⏟absolute inflow−∑lril−⏟absolute outflow \\frac{dx_i}{dt} =      \\underbrace{\\sum_j x_j r_{ji}}_{\\text{inflow}}    - \\underbrace{\\sum_j x_i r_{ij}}_{\\text{outflow}}   + \\underbrace{\\sum_k r^+_{ik}}_{\\text{absolute inflow}}   - \\underbrace{\\sum_l r^-_{il}}_{\\text{absolute outflow}} rik+r^+_{ik} absolute rate xix_i increases due mechanism kk ril−r^-_{il} absolute rate xix_i decreases due mechanism ll.","code":""},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"baseline-sir-model","dir":"Articles","previous_headings":"","what":"Baseline SIR Model","title":"Specifying Time-Varying Parameters","text":"modify SIR model transmission rate time-varying. initialize vector state labels parameter default values convenience specify simulation time 50 time steps. Using fixed transmission rate 0.8 visualize baseline SIR dynamics.","code":"state_labels = c(\"S\", \"I\", \"R\") time_steps = 50 beta = 0.8 # per-capita transmission rate gamma = 0.2 # per-capita recovery rate"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"piecewise-time-variation","dir":"Articles","previous_headings":"","what":"Piecewise Time Variation","title":"Specifying Time-Varying Parameters","text":"create piecewise time-varying transmission rate, need specify two variables: beta_changepoints - integer vector containing starting time steps transmission rate beta changes. vector starts time step 0 want specify initial default value beta followed changing transmission rates beginning time-step 10 15. (Note: Currently macpan2::time_var expects argument change_points start 0, default value beta example used. future development, time_var accept change_points[1] > 0 use default value parameter time steps change_points[1]. See Update time_var incorporate default value) beta_values numeric vector containing values beta takes time step specified beta_changepoints. need specify expression updates beta beta_values time steps beta_changepoints. use time_var function return value beta, beta_values, comparing current time step time steps beta_changepoints. Let’s test time_var computing want 20 time steps. Now know expression updating beta correctly, can modify SIR model include piece-wise transmission rate. Now plot updated simulations using change-points, highlight vertical lines. clear changes dynamics times 10 15 due drop lift transmission rate time steps.","code":"beta_changepoints = c(0, 10, 15) beta_values = c(0.8, 0.01, 0.4) # see ?time_var for arguments expr = list(  beta ~ time_var(beta_values, beta_changepoints) ) simple_sims(     iteration_exprs = expr   , time_steps = 20      # for integer vectors (usually indexing vectors) use `int_vecs`   , int_vecs = list(beta_changepoints = beta_changepoints)      # for numeric vectors (model defaults) use `mats`   # we need to initialize beta because it is a variable in our model   # so we set to 0.8 - at the beginning of the simulation loop (time_step==1)   # beta gets updated so the initial value of beta has no effect in this case   , mats = list(       beta = beta     , beta_values = beta_values)  ) |> filter(matrix == \"beta\") #>    matrix time row col value #> 1    beta    1   0   0  0.80 #> 2    beta    2   0   0  0.80 #> 3    beta    3   0   0  0.80 #> 4    beta    4   0   0  0.80 #> 5    beta    5   0   0  0.80 #> 6    beta    6   0   0  0.80 #> 7    beta    7   0   0  0.80 #> 8    beta    8   0   0  0.80 #> 9    beta    9   0   0  0.80 #> 10   beta   10   0   0  0.01 #> 11   beta   11   0   0  0.01 #> 12   beta   12   0   0  0.01 #> 13   beta   13   0   0  0.01 #> 14   beta   14   0   0  0.01 #> 15   beta   15   0   0  0.40 #> 16   beta   16   0   0  0.40 #> 17   beta   17   0   0  0.40 #> 18   beta   18   0   0  0.40 #> 19   beta   19   0   0  0.40 #> 20   beta   20   0   0  0.40 # model specification with piece-wise transmission rates piecewise_spec = (   \"starter_models\"   # read in model from library                       |> mp_tmb_library(\"sir\", package = \"macpan2\")   # insert expression for updating beta at the beginning of the simulation loop   |> mp_tmb_insert(       phase=\"during\"     , at=1     , expressions = expr     , default = list(         # Note: the default value of beta here has no effect, because at the         # first time step beta is updated to beta_values[1]         beta = beta       , gamma = gamma       , beta_values = beta_values       )     , integers = list(beta_changepoints = beta_changepoints)) ) # check that model spec was updated accordingly print(piecewise_spec) #> --------------------- #> Default values: #> --------------------- #>       matrix row col value #>         beta         8e-01 #>        gamma         2e-01 #>            N         1e+02 #>            I         1e+00 #>            R         0e+00 #>  beta_values   0     8e-01 #>  beta_values   1     1e-02 #>  beta_values   2     4e-01 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: beta ~ time_var(beta_values, beta_changepoints) #> 2: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 3: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma)  # create simulator object piecewise_simulator = (piecewise_spec    |> mp_simulator(time_steps = time_steps, outputs=c(state_labels))  )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"calibrating-time-variation-parameters","dir":"Articles","previous_headings":"","what":"Calibrating Time Variation Parameters","title":"Specifying Time-Varying Parameters","text":"First simulate data fit model , see can recover time-varying parameters.  often want include parameter constraints models, one way implicitly transform parameters (Bolker 2008). , transformations can sometimes help estimating parameters making “likelihood surface closer quadratic” reducing parameter correlation (Bolker 2008). log-transform β\\beta constraint β\\beta must positive domain logarithm (0,∞)(0, \\infty). Next create calibrator object specify want estimate vector time varying transmission rates, log_beta_values, passing parameter name par argument. optimizing, can make coefficient plot estimated values confidence intervals, compare true values.  general, transmission rate estimates follow expected pattern changing high, low, moderate. precise estimate, true value 0.8, results observed prevalence data informative transmission rate infection initially spreading. makes sense get accurate estimate final transmission rate observed data simulated final known transmission rate. lose accuracy precision middle rate 5 time steps observed data informing parameter.","code":"set.seed(1L) I_observed = (sim_data               |> filter(matrix==\"I\")               # add some poisson noise               |> mutate(value = rpois(n(),value)) ) plot(I_observed$time, I_observed$value) # transformed model specification transformed_spec = mp_tmb_insert(     model = piecewise_spec   , phase = \"before\"   , at = 1   # we need to exponentiate log transformed values so beta is on the appropriate   # scale when computing model dynamics   , expressions = list(beta_values ~ exp(log_beta_values))   # we also need to specify default values for log_beta_values   # here we set all default values for beta to the mean of the true values   # i.e. mean(log(beta_values))   , default = list(       log_beta_values = rep(mean(log(beta_values)), length(beta_values))     ) ) # Note the true values of beta (`beta_values`) are still included in the default # list, however they get updated before the simulation loop, so they are not # informing our estimates for these values when calibrating. transformed_spec #> --------------------- #> Default values: #> --------------------- #>           matrix row col      value #>             beta           0.800000 #>            gamma           0.200000 #>                N         100.000000 #>                I           1.000000 #>                R           0.000000 #>      beta_values   0       0.800000 #>      beta_values   1       0.010000 #>      beta_values   2       0.400000 #>  log_beta_values   0      -1.914868 #>  log_beta_values   1      -1.914868 #>  log_beta_values   2      -1.914868 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: beta_values ~ exp(log_beta_values) #> 2: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: beta ~ time_var(beta_values, beta_changepoints) #> 2: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 3: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) # set up calibrator object piecewise_calib = mp_tmb_calibrator(     spec = transformed_spec   , data = I_observed   , traj = \"I\"   # we want to estimate the log-transformed parameters   , par = \"log_beta_values\"   , outputs = state_labels )  # optimization step mp_optimize(piecewise_calib) #> outer mgc:  486.7233 #> Warning in (function (start, objective, gradient = NULL, hessian = NULL, : #> NA/NaN function evaluation #> outer mgc:  699.5397  #> outer mgc:  148.8469  #> outer mgc:  190.1806  #> outer mgc:  118.6255  #> outer mgc:  48.17214  #> outer mgc:  3.120084  #> outer mgc:  0.5353311  #> outer mgc:  0.01025667  #> outer mgc:  1.863369e-05  #> outer mgc:  3.959838e-11 #> $par #>     params     params     params  #> -0.2144229 -2.8405257 -0.8566479  #>  #> $objective #> [1] 94.85064 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 10 #>  #> $evaluations #> function gradient  #>       14       11  #>  #> $message #> [1] \"relative convergence (4)\""},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"radial-basis-functions-for-flexible-time-variation-in-progress","dir":"Articles","previous_headings":"","what":"Radial Basis Functions for Flexible Time Variation (In-Progress)","title":"Specifying Time-Varying Parameters","text":"section uses radial basis functions (RBFs) generate models flexible functional form smooth changes transmission rate. can add fancy radial basis transmission rate, need base model. use SIR model modified include waning. macpan2::rbf function can used produce matrix giving values basis function (column) time step (row). Using matrix, XX, weights vector, bb, can get flexible output vector, yy, shape can modified changing weights vector. y=Xb y = Xb following code illustrates approach.  d dimension basis, number functions, n number time steps. multiplying uniform basis matrix (top panel) set weights (middle panel), obtain non-uniform curve (bottom panel). Note peaks (troughs) output associated large positive (negative) weights. Now want transform output (matrix) product RBF matrix weights vector time-series transmission rate, β\\beta. Although just use output vector β\\beta time series, convenient transform β\\beta values yield interesting dynamics SIR model. particular, model βt\\beta_t function time, tt, log(βt)=log(γt)+log(N)−log(St)+xtb \\log(\\beta_t) = \\log(\\gamma_t) + \\log(N) - \\log(S_t) + x_tb recovery rate, γt\\gamma_t, number susceptibles, StS_t, time, tt, total population, NN, ttth row XX, xtx_t. better understand rationale equation note every element bb set zero, following condition. βtStN=γt \\frac{\\beta_t S_t}{N} = \\gamma_t condition assures number infected individuals remains constant time, tt. means positive values bb tend generate outbreaks negative values tend reduce transmission. fixme: (BMB) understand ’re setting model way, ’s odd/non-standard setup - may confuse people already familiar epidemic models (confused initially). simulation model radial basis exogenous transmission rate dynamics.","code":"sir_waning = mp_tmb_library(\"starter_models\"   , \"sir_waning\"   , package = \"macpan2\" ) set.seed(1L) d = 20 n = 2500 X = rbf(n, d) b = rnorm(d, sd = 0.01) par(mfrow = c(3, 1)   , mar = c(0.5, 4, 1, 1) + 0.1 ) matplot(X   , type = \"l\", lty = 1, col = 1   , ylab = \"basis functions\"   , axes = FALSE ) axis(side = 2) box() barplot(b   , xlab = \"\"   , ylab = \"weights\" ) par(mar = c(5, 4, 1, 1) + 0.1) plot(X %*% b   , type = \"l\"   , xlab = \"time\"   , ylab = \"output\" ) set.seed(1L)  spec_waning = (sir_waning              |> mp_tmb_insert(                  phase = \"before\"                , at = Inf                , expressions = list(eta ~ gamma * exp(X %*% b))                , default = list(eta = empty_matrix, X = X, b = b)              ) |> mp_tmb_insert(                  phase = \"during\"                , at = 1                , expressions = list(beta  ~ eta[time_step(1)] / clamp(S/N, 1/100))              ) )   simulator_waning = (spec_waning   |> mp_simulator(     time_steps = n   , outputs = c(\"S\", \"I\", \"R\", \"infection\", \"beta\")   , default = list(       N = 100000, I = 500, R = 0     , beta = 1, gamma = 0.2, phi = 0.01    )) )   print(simulator_waning) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #> 2: eta ~ gamma * exp(X %*% b) #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to 2500): #> --------------------- #> 1: beta ~ eta[time_step(1)]/clamp(S/N, 1/100) #> 2: infection ~ S * (I * beta/N) #> 3: recovery ~ I * (gamma) #> 4: waning_immunity ~ R * (phi) #> 5: S ~ S - infection + waning_immunity #> 6: I ~ I + infection - recovery #> 7: R ~ R + recovery - waning_immunity (simulator_waning  |> mp_trajectory()  |> ggplot()  + facet_wrap(~ matrix, ncol = 1, scales = 'free')  + geom_line(aes(time, value)) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters.html","id":"calibration","dir":"Articles","previous_headings":"Radial Basis Functions for Flexible Time Variation (In-Progress)","what":"Calibration","title":"Specifying Time-Varying Parameters","text":"can perform calibration time-varying parameter specified radial basis, using function macpan2::mp_rbf(). follow ususal steps calibration. 1. Simulate model add poisson noise: 2. Add calibration information. 3. Review results. fit observed data looks reasonable, however obvious wiggly deviations.","code":"obs_rbf = (simulator_waning  |> mp_trajectory()  |> filter(matrix==\"I\")  |> mutate(across(value, ~ rpois(n(), .))) ) calib_rbf = mp_tmb_calibrator(sir_waning    , data = obs_rbf    , traj = \"I\"    ## estimate     , par = \"beta\"    , tv = mp_rbf(\"beta\", dimension = d, initial_weights = b)    ## pass all defaults, including dimension of the rbf `d` and initial weights vector `b`    , default = list(N = 100000, I = 500, R = 0, beta = 1, gamma = 0.2, phi = 0.01, d = d, b = b)     )    mp_optimize(calib_rbf) #> outer mgc:  260404.5  #> outer mgc:  516278.6  #> outer mgc:  587174.9  #> outer mgc:  650089  #> outer mgc:  551580.4  #> outer mgc:  577141  #> outer mgc:  544591  #> outer mgc:  343582.7  #> outer mgc:  219354.8  #> outer mgc:  474385.6  #> outer mgc:  759175.8  #> outer mgc:  1981896  #> outer mgc:  572674.8  #> outer mgc:  130718.1  #> outer mgc:  11623.46  #> outer mgc:  2573.963  #> outer mgc:  250.8778  #> outer mgc:  3.075834  #> outer mgc:  0.0004771355 #> $par #>      params      params      params      params      params      params  #> -1.27641280 -0.23972069 -0.88918700 -0.48246900 -0.71662892 -0.54489211  #>      params      params      params      params      params      params  #> -0.66403205 -0.55987089 -0.60953016 -0.48826067 -0.53743851 -0.35883656  #>      params      params      params      params      params      params  #>  0.01438706 -0.51734442 -0.50528656 -0.51390784 -0.56715449 -0.36571049  #>      params      params      params  #> -0.67953264  0.38050808  0.55256296  #>  #> $objective #> [1] 30057.53 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 19 #>  #> $evaluations #> function gradient  #>       32       19  #>  #> $message #> [1] \"both X-convergence and relative convergence (5)\" ## check estimates mp_tmb_coef(calib_rbf,conf.int = TRUE) #> outer mgc:  0.0004771355  #> outer mgc:  10106.35  #> outer mgc:  10244.65  #> outer mgc:  18039.69  #> outer mgc:  18377.17  #> outer mgc:  17661.5  #> outer mgc:  18052.09  #> outer mgc:  17007.5  #> outer mgc:  17390.3  #> outer mgc:  12227.71  #> outer mgc:  12481.76  #> outer mgc:  9350.09  #> outer mgc:  9523.219  #> outer mgc:  8689.409  #> outer mgc:  8849.081  #> outer mgc:  7212.485  #> outer mgc:  7337.635  #> outer mgc:  4499.09  #> outer mgc:  4557.787  #> outer mgc:  2639.332  #> outer mgc:  2663.877  #> outer mgc:  1474.115  #> outer mgc:  1484.504  #> outer mgc:  630.3664  #> outer mgc:  632.9975  #> outer mgc:  367.2692  #> outer mgc:  368.5147  #> outer mgc:  926.993  #> outer mgc:  932.217  #> outer mgc:  2072.398  #> outer mgc:  2092.068  #> outer mgc:  2411.296  #> outer mgc:  2433.905  #> outer mgc:  2161.669  #> outer mgc:  2180.24  #> outer mgc:  1396.096  #> outer mgc:  1405.354  #> outer mgc:  696.5062  #> outer mgc:  699.8151  #> outer mgc:  211.0486  #> outer mgc:  211.5534  #> outer mgc:  89.26982  #> outer mgc:  90.08222  #> outer mgc:  7442.986 #>         term           mat row col       default  type    estimate   std.error #> 1     params time_var_beta   0   0 -0.0062645381 fixed -1.27641280 0.001463832 #> 2   params.1 time_var_beta   1   0  0.0018364332 fixed -0.23972069 0.001977560 #> 3  params.10 time_var_beta  10   0  0.0151178117 fixed -0.53743851 0.002792037 #> 4  params.11 time_var_beta  11   0  0.0038984324 fixed -0.35883656 0.003704611 #> 5  params.12 time_var_beta  12   0 -0.0062124058 fixed  0.01438706 0.004098547 #> 6  params.13 time_var_beta  13   0 -0.0221469989 fixed -0.51734442 0.003224495 #> 7  params.14 time_var_beta  14   0  0.0112493092 fixed -0.50528656 0.002548279 #> 8  params.15 time_var_beta  15   0 -0.0004493361 fixed -0.51390784 0.002403806 #> 9  params.16 time_var_beta  16   0 -0.0001619026 fixed -0.56715449 0.002599612 #> 10 params.17 time_var_beta  17   0  0.0094383621 fixed -0.36571049 0.003240611 #> 11 params.18 time_var_beta  18   0  0.0082122120 fixed -0.67953264 0.004104058 #> 12 params.19 time_var_beta  19   0  0.0059390132 fixed  0.38050808 0.004919260 #> 13  params.2 time_var_beta   2   0 -0.0083562861 fixed -0.88918700 0.002074339 #> 14 params.20 prior_sd_beta   0   0  1.0000000000 fixed  0.55256296 0.003339349 #> 15  params.3 time_var_beta   3   0  0.0159528080 fixed -0.48246900 0.001927518 #> 16  params.4 time_var_beta   4   0  0.0032950777 fixed -0.71662892 0.001755581 #> 17  params.5 time_var_beta   5   0 -0.0082046838 fixed -0.54489211 0.001597672 #> 18  params.6 time_var_beta   6   0  0.0048742905 fixed -0.66403205 0.001506794 #> 19  params.7 time_var_beta   7   0  0.0073832471 fixed -0.55987089 0.001518645 #> 20  params.8 time_var_beta   8   0  0.0057578135 fixed -0.60953016 0.001727385 #> 21  params.9 time_var_beta   9   0 -0.0030538839 fixed -0.48826067 0.002143931 #>        conf.low   conf.high #> 1  -1.279281858 -1.27354374 #> 2  -0.243596641 -0.23584475 #> 3  -0.542910801 -0.53196622 #> 4  -0.366097459 -0.35157565 #> 5   0.006354052  0.02242006 #> 6  -0.523664313 -0.51102453 #> 7  -0.510281099 -0.50029203 #> 8  -0.518619216 -0.50919647 #> 9  -0.572249636 -0.56205934 #> 10 -0.372061971 -0.35935901 #> 11 -0.687576449 -0.67148884 #> 12  0.370866505  0.39014965 #> 13 -0.893252629 -0.88512137 #> 14  0.546017957  0.55910797 #> 15 -0.486246869 -0.47869114 #> 16 -0.720069797 -0.71318804 #> 17 -0.548023491 -0.54176073 #> 18 -0.666985316 -0.66107879 #> 19 -0.562847379 -0.55689440 #> 20 -0.612915777 -0.60614455 #> 21 -0.492462697 -0.48405864"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"baseline-sir-model","dir":"Articles","previous_headings":"","what":"Baseline SIR Model","title":"Advanced Specification of Time-Varying Parameters","text":"modify SIR model transmission rate time-varying.","code":"state_labels = c(\"S\", \"I\", \"R\") simulator = (\"starter_models\"   |> mp_tmb_library(\"sir\", package = \"macpan2\")   |> mp_simulator(time_steps = 50     , outputs = state_labels     , default = list(beta = 0.8, gamma = 0.2)   ) ) (simulator   |> mp_trajectory()   |> mutate(state = factor(matrix, state_labels))   |> ggplot()    + geom_line(aes(time, value, colour = state)) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"piecewise-time-variation","dir":"Articles","previous_headings":"","what":"Piecewise Time Variation","title":"Advanced Specification of Time-Varying Parameters","text":"now change value transmission rate, beta, beginning time-step 10 15. first step add simulator vector containing change-points. Next add values beta changes time-steps. also need variable track current value beta. beta_pointer starts time-step equal 0, incremented throughout simulation. increment beta_pointer using time_group function returns either beta_pointer beta_pointer + 1 depending whether current time-step change-point beta_changepoints. update beta every iteration simulation loop using beta_pointer. Now plot updated simulations using change-points, highlight vertical lines.  clear kinks times 10 15 due drop lift transmission rate times.","code":"simulator$add$matrices(beta_changepoints = c(0, 10, 15)) simulator$add$matrices(beta_values = c(0.8, 0.01, 0.4)) simulator$add$matrices(beta_pointer = 0) simulator$insert$expressions(     beta_pointer ~ time_group(beta_pointer, beta_changepoints),      .phase = \"during\" ) simulator$insert$expressions(   beta ~ beta_values[beta_pointer],   .phase = \"during\" ) s = mp_trajectory(simulator) cp = simulator$get$initial(\"beta_changepoints\") (s   %>% mutate(state = factor(matrix, state_labels))   %>% ggplot()   + geom_line(aes(time, value, colour = state))   + geom_vline(     aes(xintercept = x),      linetype = \"dashed\",      alpha = 0.5,      data = data.frame(x = cp)   ) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"calibrating-time-variation-parameters","dir":"Articles","previous_headings":"","what":"Calibrating Time Variation Parameters","title":"Advanced Specification of Time-Varying Parameters","text":"First simulate data fit model , see can recover time-varying parameters.  add matrices model keeping tracking information used model fitting. Now need new expressions. first expression pulls state state vector. second expression computes vector Poisson log-likelihood values – one time step. Next declare beta values parameters optimized log scale. clearest way form data frame one row parameter fitted. couple potentially confusing aspects data frame. First, want fit beta values log scale, indicate prepending log_ front name beta_values matrix model. explicitly add log_beta_values matrix model next code chunk. Second, word row corresponds index change points. particular, row = 0 corresponds initial beta, row = 1 first change point row = 2 second. quantities passed macpan2 engines matrices, case different rows log_beta_values matrix (actually column vector) correspond different change points. dealing matrices one column need include col column data frame indicate matrix columns matrix entries correspond parameters fitted. Now log transform beta_values matrix entries declare parameters. Finally fit model back simulation data. can see optimizer converges (.e. $convergence = 0) 26 iterations. log scale see optimizer finds different values (current) started (default). importantly beta values untransformed scale recover reasonable values qualitatively consistent values used simulations. Note however second fitted beta value much smaller true value, potentially interesting.","code":"set.seed(1L) I_observed = rpois(50   , filter(s, matrix == \"I\")$value ) plot(I_observed) simulator$update$matrices(      ## observed data   I_obs = I_observed,      ## simulated trajectory to compare with data   I_sim = empty_matrix,       ## location of I in the state vector   ## (the `-1L` bit is to get 0-based indices instead of 1-based)   I_index = match(\"I\", state_labels) - 1L,       ## matrix to contain the log likelihood values at    ## each time step   log_lik = empty_matrix,       ## need to save the simulation history of each of these matrices   .mats_to_save = c(\"I_sim\", \"log_lik\") ) simulator$insert$expressions(   I_sim ~ I,   .phase = \"during\" ) simulator$insert$expressions(   log_lik ~ dpois(I_obs, clamp(rbind_time(I_sim))),   .phase = \"after\" ) simulator$replace$obj_fn(~ -sum(log_lik)) default_beta = mean(simulator$get$initial(\"beta_values\")) params_to_fit = data.frame(     mat = \"log_beta_values\"   , row = 0:2   , default = log(default_beta) ) print(params_to_fit) #>               mat row    default #> 1 log_beta_values   0 -0.9079919 #> 2 log_beta_values   1 -0.9079919 #> 3 log_beta_values   2 -0.9079919 simulator$add$transformations(Log(\"beta_values\")) simulator$replace$params_frame(params_to_fit) simulator$optimize$nlminb() #> outer mgc:  736.1414  #> outer mgc:  112.6655  #> outer mgc:  71.38648  #> outer mgc:  13.6616  #> outer mgc:  12.58091  #> outer mgc:  3.638083  #> outer mgc:  1.399513  #> outer mgc:  1.609453  #> outer mgc:  1.140347  #> outer mgc:  0.5870909  #> outer mgc:  0.2527136  #> outer mgc:  0.09938628  #> outer mgc:  0.03753935  #> outer mgc:  0.01394885  #> outer mgc:  0.005150654  #> outer mgc:  0.001897432  #> outer mgc:  0.0006983805  #> outer mgc:  0.0002569678  #> outer mgc:  9.453968e-05  #> outer mgc:  3.478009e-05  #> outer mgc:  1.2795e-05  #> outer mgc:  4.707033e-06  #> outer mgc:  1.731623e-06  #> outer mgc:  6.370285e-07  #> outer mgc:  2.343501e-07  #> outer mgc:  8.621238e-08  #> outer mgc:  3.171574e-08 #> $par #>      params      params      params  #>  -0.1710158 -22.8268369  -0.8291142  #>  #> $objective #> [1] 99.74231 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 26 #>  #> $evaluations #> function gradient  #>       28       27  #>  #> $message #> [1] \"relative convergence (4)\" simulator$current$params_frame() #>   par_id             mat row col    default     current #> 1      0 log_beta_values   0   0 -0.9079919  -0.1710158 #> 2      1 log_beta_values   1   0 -0.9079919 -22.8268369 #> 3      2 log_beta_values   2   0 -0.9079919  -0.8291142 data.frame(   fitted = formatC(     exp(simulator$current$params_frame()$current),     format = \"e\", digits = 2   ),   true = simulator$get$initial(\"beta_values\") ) #>     fitted true #> 1 8.43e-01 0.80 #> 2 1.22e-10 0.01 #> 3 4.36e-01 0.40"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"radial-basis-functions-for-flexible-time-variation-in-progress","dir":"Articles","previous_headings":"","what":"Radial Basis Functions for Flexible Time Variation (In-Progress)","title":"Advanced Specification of Time-Varying Parameters","text":"section uses radial basis functions (RBFs) generate models flexible functional form smooth changes transmission rate. can add fancy radial basis transmission rate, need base model. use SIR model modified include waning. macpan2::rbf function can used produce matrix giving values basis function (column) time step (row). Using matrix, XX, weights vector, bb, can get flexible output vector, yy, shape can modified changing weights vector. y=Xb y = Xb following code illustrates approach.  d dimension basis, number functions, n number time steps. multiplying uniform basis matrix (top panel) set weights (middle panel), obtain non-uniform curve (bottom panel). Note peaks (troughs) output associated large positive (negative) weights. Now want transform output (matrix) product RBF matrix weights vector time-series transmission rate, β\\beta. Although just use output vector β\\beta time series, convenient transform β\\beta values yield interesting dynamics SIR model. particular, model βt\\beta_t function time, tt, log(βt)=log(γt)+log(N)−log(St)+xtb \\log(\\beta_t) = \\log(\\gamma_t) + \\log(N) - \\log(S_t) + x_tb recovery rate, γt\\gamma_t, number susceptibles, StS_t, time, tt, total population, NN, ttth row XX, xtx_t. better understand rationale equation note every element bb set zero, following condition. βtStN=γt \\frac{\\beta_t S_t}{N} = \\gamma_t condition assures number infected individuals remains constant time, tt. means positive values bb tend generate outbreaks negative values tend reduce transmission. fixme: (BMB) understand ’re setting model way, ’s odd/non-standard setup - may confuse people already familiar epidemic models (confused initially). simulation model radial basis exogenous transmission rate dynamics.","code":"sir = mp_tmb_library(\"starter_models\"   , \"sir_waning\"   , package = \"macpan2\" ) set.seed(1L) d = 20 n = 2500 X = rbf(n, d) b = rnorm(d, sd = 0.01) par(mfrow = c(3, 1)   , mar = c(0.5, 4, 1, 1) + 0.1 ) matplot(X   , type = \"l\", lty = 1, col = 1   , ylab = \"basis functions\"   , axes = FALSE ) axis(side = 2) box() barplot(b   , xlab = \"\"   , ylab = \"weights\" ) par(mar = c(5, 4, 1, 1) + 0.1) plot(X %*% b   , type = \"l\"   , xlab = \"time\"   , ylab = \"output\" ) set.seed(1L) simulator = mp_simulator(sir   , time_steps = n   , outputs = c(\"S\", \"I\", \"R\", \"infection\", \"beta\")   , default = list(       N = 100000, I = 500, R = 0     , beta = 1, gamma = 0.2, phi = 0.01     , X = rbf(n, d)     , b = rnorm(d, sd = 0.01)   ) ) simulator$insert$expressions(     eta ~ gamma * exp(X %*% b)   , .phase = \"before\"   , .at = Inf ) simulator$insert$expressions(     beta ~ eta[time_step(1)] / clamp(S/N, 1/100)   , .phase = \"during\"   , .at = 1 ) simulator$add$matrices(     eta = empty_matrix ) simulator$replace$params(     default = rnorm(d, sd = 0.01)   , mat = rep(\"b\", d)   , row = seq_len(d) - 1L ) print(simulator) #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #> 2: eta ~ gamma * exp(X %*% b) #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to 2500): #> --------------------- #> 1: beta ~ eta[time_step(1)]/clamp(S/N, 1/100) #> 2: infection ~ S * (I * beta/N) #> 3: recovery ~ I * (gamma) #> 4: waning_immunity ~ R * (phi) #> 5: S ~ S - infection + waning_immunity #> 6: I ~ I + infection - recovery #> 7: R ~ R + recovery - waning_immunity (simulator  |> mp_trajectory()  |> ggplot()  + facet_wrap(~ matrix, ncol = 1, scales = 'free')  + geom_line(aes(time, value)) )"},{"path":"https://canmod.github.io/macpan2/articles/time_varying_parameters_advanced.html","id":"calibration","dir":"Articles","previous_headings":"Radial Basis Functions for Flexible Time Variation (In-Progress)","what":"Calibration","title":"Advanced Specification of Time-Varying Parameters","text":"Now ’re going calibrate model data. main innovation use built-feature TMB (macpan2 constructed), estimation latent variables Laplace approximation fit time series efficiently without overfitting (see section 5.10 Madsen Thyregod (2011), Kristensen et al. (2016), TMB documentation detail). next steps roughly follow first example Calibration vignette: TODO: make sure line state specific code calibration vignette. 1. Simulate model add noise:  2. Add calibration information. start adding standard boilerplate stuff include observed data store/return results. Now start deviate previous example: addition parameter (I_sd) standard deviation noise II, also add parameter (rbf_sd) variance RBF coefficients, penalize likelihood using Iobs∼Normal(Isim(ϕ,𝐛),σI2)bi∼Normal(0,σrbf2) \\begin{split} I_{\\textrm{obs}} & \\sim \\textrm{Normal}(I_\\textrm{sim}(\\phi, {\\mathbf b}), \\sigma^2_I) \\\\ b_i & \\sim \\textrm{Normal}(0, \\sigma^2_{\\textrm{rbf}}) \\end{split}  likelihood defined : $$ \\int {\\cal L}(I_{\\textrm{obs}}|\\phi, {\\mathbf b}', \\sigma^2_I) \\cdot {\\cal L}({\\mathbf b}'|\\sigma^2_{\\textrm{rbf}}) \\, d{\\mathbf b}. $$ ϕ\\phi vector set fixed-effect (unpenalized) parameters; case empty, include (example) time-constant recovery immune-waning rates, baseline transmission rate (see note ). (fixed-effect parameter usually denoted β\\beta statistical models, ’ve already used symbol transmission coefficient …) Although looks awful, (1) high-dimensional integral 𝐛\\mathbf b can separated product one-dimensional integrals (2) Laplace approximation gives us quick, reasonable approximation one-dimensional integrals. rbf_sd parameter can interpreted standard deviation Gaussian random effect approximately 1/λ1/\\sqrt{\\lambda} λ\\lambda ridge penalty. Continuing coding, add parameters negative log-likelihood model, making negative log-likelihood sum two terms integral : NLL data (-sum(dnorm(I_obs, ...))) likelihood RBF parameters (-sum(dnorm(b, ...))): fit SD parameters log scale. Finally, add b vector set random parameters: tells macpan2 apply Laplace approximation parameters … Test objective function: fixme: can’t get objective function shut . specified silent = TRUE calling MakeADFun() initially, now tried assigning value several different environments, without success … step normally produces lots output (output model random effects) Laplace approximation involves additional “inner” step b parameters optimized, even though evaluating objective single set fixed parameters (log_I_sd, log_rbf_sd) fixme: note developers, cache results may need call $retape() function restore internal structure retrieving … fixme: need incantation extract full parameters (including RE parameters) order make sure $report works properly? (general, caution mutability/make sure use last.par.best internally …) Extract parameters, run simulator best-fit parameters, compare data …  fixme: artificialities example /relaxed fixed parameters standard deviations. Normally also estimating gamma (possibly prior? examples, say calibration vignette, adding priors?) RBF function penalized zero. general, augment penalized RBF component (determines variation around mean) unpenalized intercept/baseline transmission parameter. , example, transmission rate computed b0 + exp(X %*% b), b0 represents unpenalized parameter ’s allowed vary freely … fixme: compare (1) unpenalized fit; (2) penalized fit without Laplace approximation … fixme: discuss (somewhere) alternate bases latent variables (random-walk, Gaussian process, …)","code":"obs_I <- (simulator     |> mp_trajectory()     |> filter(matrix == \"I\")     |> mutate(across(value, ~ rnorm(n(), ., sd = 50)))     |> pull(value) ) plot(obs_I, xlab = \"time\", ylab = \"prevalence\") ## copied from 'calibration/\"hello world\"' example simulator$add$matrices(     I_obs = obs_I   , I_sim = empty_matrix   , log_lik = empty_matrix   , .mats_to_save = c(\"I_sim\")   , .mats_to_return = c(\"I_sim\") ) simulator$insert$expressions(      I_sim ~ I    , .phase = \"during\"    , .at = Inf ) simulator$add$matrices(     I_sd = 1   , rbf_sd = 1 ) simulator$insert$expressions(      log_lik ~         -sum(dnorm(I_obs, rbind_time(I_sim), I_sd)) +        -1*sum(dnorm(b, 0.0, rbf_sd)),      .phase = \"after\" ) ## initially forgot this: maybe we could warn when someone is missing this???? simulator$replace$obj_fn(~ log_lik) simulator$add$transformations(Log(\"I_sd\")) simulator$add$transformations(Log(\"rbf_sd\")) ## not sure if this is required? params <- read.delim(sep = \"|\", header = TRUE,                      strip.white = TRUE, ## important!                       text = \" mat         | default log_I_sd    | 0 log_rbf_sd  | 1 \") simulator$replace$params_frame(params) matrix_version = \"1.6-5\" if (packageVersion(\"Matrix\") >= matrix_version) {   rparams <- data.frame(       mat  = \"b\",       row = 0:19,       col = 0,       default = 0)   simulator$replace$random_frame(rparams) } if (packageVersion(\"Matrix\") >= matrix_version) {   res <- simulator$ad_fun()$fn(c(1,1)) } #> iter: 1  value: 5994496 mgc: 2058657968 ustep: 1  #> iter: 2  value: 1327494 mgc: 1334286157 ustep: 1  #> iter: 3  value: 539106 mgc: 359174176 ustep: 1  #> iter: 4  value: 461675.4 mgc: 72820581 ustep: 1  #> iter: 5  value: 458020.4 mgc: 9231141 ustep: 1  #> iter: 6  value: 457980.9 mgc: 605743.9 ustep: 1  #> iter: 7  value: 457980.9 mgc: 7692.96 ustep: 1  #> iter: 8  value: 457980.9 mgc: 2.548908 ustep: 1  #> iter: 9  value: 457980.9 mgc: 1.89712e-06 ustep: 1  #> mgc: 8.929342e-07 #> [1] 458152.8 #> attr(,\"logarithm\") #> [1] TRUE if (packageVersion(\"Matrix\") >= matrix_version) {   ## testing: simulator$ad_fun()$fn()   fit <- simulator$optimize$nlminb() } if (packageVersion(\"Matrix\") >= matrix_version) {    ## simulator$print$matrix_dims()   ## fixed effects only:   ## look at parameters, but skip the random-effects parameters   ## 'random' holds the indices of the parameters that are treated   ## as random effects   (fixed_params <- with(simulator$ad_fun()$env,                         last.par.best[-random]))   ## ???   ## RE only   (ran_params <- with(simulator$ad_fun()$env,                       last.par.best[random])) } #>        random        random        random        random        random  #>  0.0067466350  0.0116662413 -0.0036351505 -0.0151989880  0.0011403827  #>        random        random        random        random        random  #>  0.0032615158 -0.0028962068 -0.0146686471 -0.0058110019  0.0073568463  #>        random        random        random        random        random  #>  0.0097221102  0.0023726453  0.0007574901  0.0014761570 -0.0134865091  #>        random        random        random        random        random  #> -0.0068787221 -0.0025147741  0.0027382985  0.0086679247  0.0033013692 if (packageVersion(\"Matrix\") >= matrix_version) {   pp <- simulator$ad_fun()$env$last.par.best  ## FIXME: use this   est_I <- (simulator       |> mp_trajectory()       |> filter(matrix == \"I\")       |> pull(value)   )   par(las = 1, bty = \"l\")   plot(obs_I, xlab = \"time\", ylab = \"prevalence\")   lines(est_I, col = 2, lwd = 2) }"},{"path":[]},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"stable","dir":"Articles","previous_headings":"","what":"Stable","title":"Article Status","text":"– Please read! Although mistakes always possible, please open issue find .","code":""},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"mature-draft","dir":"Articles","previous_headings":"","what":"Mature Draft","title":"Article Status","text":"– consistent accurate, yet widely utilized /checked correctness.","code":""},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"working-draft","dir":"Articles","previous_headings":"","what":"Working Draft","title":"Article Status","text":"– Makes sense, well inconsistent confusing.","code":""},{"path":"https://canmod.github.io/macpan2/articles/vignette_status.html","id":"stub","dir":"Articles","previous_headings":"","what":"Stub","title":"Article Status","text":"– even bother reading.","code":""},{"path":"https://canmod.github.io/macpan2/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Steve Walker. Maintainer, author. Weiguang Guan. Author. Jen Freeman. Author. Ben Bolker. Author. Darren Flynn-Primrose. Author. Irena Papst. Contributor. Michael Li. Contributor.","code":""},{"path":"https://canmod.github.io/macpan2/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Steve Walker, Weiguang Guan, Jen Freeman, Ben Bolker, Darren Flynn-Primrose (2024). macpan2: Fast Flexible Compartmental Modelling. R package version 1.11.1, https://github.com/canmod/macpan2, https://canmod.github.io/macpan2/.","code":"@Manual{,   title = {macpan2: Fast and Flexible Compartmental Modelling},   author = {{Steve Walker} and {Weiguang Guan} and {Jen Freeman} and {Ben Bolker} and {Darren Flynn-Primrose}},   year = {2024},   note = {R package version 1.11.1, https://github.com/canmod/macpan2},   url = {https://canmod.github.io/macpan2/}, }"},{"path":"https://canmod.github.io/macpan2/index.html","id":"macpan2","dir":"","previous_headings":"","what":"Fast and Flexible Compartmental Modelling","title":"Fast and Flexible Compartmental Modelling","text":"McMasterPandemic developed provide forecasts insights Canadian public health agencies throughout COVID-19 pandemic. Much learned developing general purpose compartmental modelling software experience, pressure deliver regular forecasts made difficult focus software . goal macpan2 project re-imagine McMasterPandemic, building ground architectural technological decisions address many lessons learned COVID-19 software. Impactful applied public health modelling requires many interdisciplinary steps along path epidemiological research teams operational decision makers. Researchers must quickly tailor model emerging public-health concern, validate calibrate data, work decision makers define model outputs useful stakeholders, configure models generate outputs, package insights appropriate format stakeholders. Unlike traditional modelling approaches, macpan2 tackles challenge software-engineering perspective, allows us systematically address bottlenecks along path impact ways make future solutions easier achieve. goal enable researchers focus core strengths fill knowledge gaps efficiently effectively. Although macpan2 designed compartmental modelling tool agnostic underlying computational engine, currently uses template model builder sole engine. Template model builder (TMB) R modelling package based C++ framework incorporating mature automatic differentiation matrix algebra libraries. Public Health Risk Sciences Division Public Health Agency Canada uses macpan2 (example, ).","code":""},{"path":"https://canmod.github.io/macpan2/index.html","id":"documentation","dir":"","previous_headings":"","what":"Documentation","title":"Fast and Flexible Compartmental Modelling","text":"Package reference Quick-start guide TMB engine [specification document] Project history trajectory [slides]","code":""},{"path":"https://canmod.github.io/macpan2/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Fast and Flexible Compartmental Modelling","text":"standard recommended way install macpan2 following command. command install current version macpan2. projects production need keep track specific versions macpan2, snapshots reproducibility information can obtained . Please see article explanation manage reproducibility using r-universe. get latest development version macpan2, command fails reason, alternative command install following. command requires remotes package assumes R environment set compile C++ code contained packages. Many workflows macpan2 also make use following packages.","code":"repos = c('https://canmod.r-universe.dev', 'https://cloud.r-project.org') install.packages('macpan2', repos = repos) remotes::install_github(\"canmod/macpan2\") install.packages(c(\"dplyr\", \"ggplot2\", \"tidyr\", \"broom.mixed\"))"},{"path":"https://canmod.github.io/macpan2/index.html","id":"hello-world","dir":"","previous_headings":"","what":"Hello World","title":"Fast and Flexible Compartmental Modelling","text":"following code specifies SI model, simplest model epidemiological transmission. See article example models documentation. Simulating model requires choosing number time-steps run model outputs generate. Syntax simulating macpan2 models designed combine standard data prep plotting tools R, demonstrate following code.","code":"library(macpan2) si = mp_tmb_model_spec(     before = S ~ 1 - I   , during = mp_per_capita_flow(         from     = \"S\"         ## compartment from which individuals flow       , to       = \"I\"         ## compartment to which individuals flow       , rate     = \"beta * I\"  ## expression giving _per-capita_ flow rate       , abs_rate = \"infection\" ## name for _absolute_ flow rate = beta * I * S     )   , default = list(I = 0.01, beta = 0.2) ) print(si) ## --------------------- ## Default values: ## --------------------- ##  matrix row col value ##       I          0.01 ##    beta          0.20 ##  ## --------------------- ## Before the simulation loop (t = 0): ## --------------------- ## 1: S ~ 1 - I ##  ## --------------------- ## At every iteration of the simulation loop (t = 1 to T): ## --------------------- ## 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I\", abs_rate = \"infection\") library(ggplot2) library(dplyr) (si  |> mp_simulator(time_steps = 50, outputs = c(\"I\", \"infection\"))  |> mp_trajectory()  |> mutate(quantity = case_match(matrix     , \"I\" ~ \"Prevalance\"     , \"infection\" ~ \"Incidence\"   ))  |> ggplot()   + geom_line(aes(time, value))   + facet_wrap(~ quantity, scales = \"free\")  + theme_bw() )"},{"path":"https://canmod.github.io/macpan2/index.html","id":"product-management","dir":"","previous_headings":"","what":"Product Management","title":"Fast and Flexible Compartmental Modelling","text":"project board tracks details bugs, tasks, feature development.","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":null,"dir":"Reference","previous_headings":"","what":"Binary Operator — BinaryOperator","title":"Binary Operator — BinaryOperator","text":"Convert function represents elementwise binary operator one consistent C++ engine. function intended clarify macpan2 treats binary operators, little different base R. difference clarified vignette(\"elementwise_binary_operators\"), BinaryOperator primarily used resource vignette.","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Binary Operator — BinaryOperator","text":"","code":"BinaryOperator(operator)"},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Binary Operator — BinaryOperator","text":"operator binary operator. Valid binary operations following characteristics.  - functions.  - exactly two arguments.  - ... arguments","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Binary Operator — BinaryOperator","text":"binary operator consistent C++ engine.","code":""},{"path":"https://canmod.github.io/macpan2/reference/BinaryOperator.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Binary Operator — BinaryOperator","text":"","code":"set.seed(1L) A = matrix(abs(rnorm(6)), 3, 2)  # 3 by 2 matrix x = matrix(abs(rnorm(3)))        # 3 by 1 matrix y = t(abs(rnorm(2)))             # 1 by 2 matrix times = BinaryOperator(`*`) pow = BinaryOperator(`^`) identical(times(A, x), times(x, A))  ## TRUE #> [1] TRUE identical(pow(A, y), pow(y, A))  ## FALSE #> [1] FALSE"},{"path":"https://canmod.github.io/macpan2/reference/LedgerDefinition.html","id":null,"dir":"Reference","previous_headings":"","what":"Ledgers — LedgerDefinition","title":"Ledgers — LedgerDefinition","text":"ledger table rows identify specific instances functional form used define mp_dynamic_model. Ledgers commonly created using mp_join function following example.","code":"age = mp_index(Age = c(\"young\", \"old\")) state = mp_cartesian(   mp_index(Epi = c(\"S\", \"I\", \"R\")),   age ) mp_join(   from = mp_subset(state, Epi = \"S\"),   to = mp_subset(state, Epi = \"I\"),   by = list(from.to = \"Age\") ) #>     from      to #>  S.young I.young #>    S.old   I.old"},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":null,"dir":"Reference","previous_headings":"","what":"Reader — Reader","title":"Reader — Reader","text":"Construct objects reading data.","code":""},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reader — Reader","text":"","code":"Reader(...)  CSVReader(...)  JSONReader(...)  TXTReader(...)  RReader(...)  NULLReader(...)"},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reader — Reader","text":"... Character vectors giving path components file read.","code":""},{"path":"https://canmod.github.io/macpan2/reference/Reader.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Reader — Reader","text":"CSVReader(): Read CSV files. JSONReader(): Read JSON files. TXTReader(): Read TXT files. RReader(): Read R files. NULLReader(): Placeholder reader always returns NULL.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":null,"dir":"Reference","previous_headings":"","what":"String Data — StringData","title":"String Data — StringData","text":"Create objects representing names labels dynamical model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"String Data — StringData","text":"","code":"StringDataFromFrame(data)  StringDataFromDotted(labels, name)  # S3 method for class 'StringData' print(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"String Data — StringData","text":"data Data frame names given column names labels elements columns. labels Character vector (dot-separated) partition labels. name Character scalar (dot-separated) partition name. x StringData object ... used present S3 method consistency.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"methods-by-generic-","dir":"Reference","previous_headings":"","what":"Methods (by generic)","title":"String Data — StringData","text":"print(StringData): Print StringData object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"String Data — StringData","text":"StringDataFromFrame(): Construct object data frame without dots either names values. StringDataFromDotted(): Construct object character scalar (dot-separated) partition names character vector (dot-separated) partition labels.","code":""},{"path":"https://canmod.github.io/macpan2/reference/StringData.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"String Data — StringData","text":"","code":"vars = (mp_cartesian(       mp_index(Epi = c(\"S\", \"I\", \"R\"))     , mp_index(Age = c(\"young\", \"old\"))   )   |> as.data.frame()   |> StringDataFromFrame() ) vars #> String data object with the following $frame(): #>   Epi   Age #> 1   S young #> 2   I young #> 3   R young #> 4   S   old #> 5   I   old #> 6   R   old vars$dot() #> String data object with the following $frame(): #>   Epi.Age #> 1 S.young #> 2 I.young #> 3 R.young #> 4   S.old #> 5   I.old #> 6   R.old"},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":null,"dir":"Reference","previous_headings":"","what":"Transform — Transform","title":"Transform — Transform","text":"Transform","code":""},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Transform — Transform","text":"","code":"Transform(variable, default = NULL, trans_variable = variable)  Identity(variable, default = NULL, trans_variable = variable)  Log(variable, default = NULL, trans_variable = sprintf(\"log_%s\", variable))  Logit(   variable,   default = NULL,   trans_variable = sprintf(\"logit_%s\", variable) )"},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Transform — Transform","text":"variable Character string giving name variable model. default Default value untransformed variable. NULL (default) value taken initial value model containing transformation. trans_variable Character string use name transformed version variable.","code":""},{"path":"https://canmod.github.io/macpan2/reference/Transform.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Transform — Transform","text":"Identity(): Identity transformation. Log(): Log transformation. Logit(): Logit transformation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":null,"dir":"Reference","previous_headings":"","what":"Comparison Functions — comparison","title":"Comparison Functions — comparison","text":"Comparison Functions","code":""},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Comparison Functions — comparison","text":"","code":"all_equal(x, y)  all_consistent(x, y)  not_all_equal(x, y)  all_not_equal(x, y)"},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Comparison Functions — comparison","text":"x character object y character object","code":""},{"path":"https://canmod.github.io/macpan2/reference/comparison.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Comparison Functions — comparison","text":"all_equal(): true corresponding elements x y equal, shape, missing values? all_consistent(): true corresponding elements x y either equal least one blank string, shape, missing values? not_all_equal(): Complement all_equal. all_not_equal(): know yet. Currently unused; remove?","code":""},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":null,"dir":"Reference","previous_headings":"","what":"Distributions — distribution","title":"Distributions — distribution","text":"Distributions can used specify prior likelihood components model calibration. Uniform Distribution (Improper), appropriate prior components - mp_uniform Normal Distribution - mp_normal Log-Normal Distribution - mp_log_normal Logit-Normal Distribution - mp_logit_normal Poisson Distribution - mp_poisson Negative Binomial Distribution - mp_neg_bin","code":""},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Distributions — distribution","text":"","code":"mp_uniform(trans_distr_param = list())  mp_normal(   location = mp_distr_param_null(\"location\"),   sd,   trans_distr_param = list(location = mp_identity, sd = mp_log) )  mp_log_normal(   location = mp_distr_param_null(\"location\"),   sd,   trans_distr_param = list(location = mp_identity, sd = mp_identity) )  mp_logit_normal(   location = mp_distr_param_null(\"location\"),   sd,   trans_distr_param = list(location = mp_identity, sd = mp_identity) )  mp_poisson(   location = mp_distr_param_null(\"location\"),   trans_distr_param = list(location = mp_identity) )  mp_neg_bin(   location = mp_distr_param_null(\"location\"),   disp,   trans_distr_param = list(location = mp_identity, disp = mp_log) )"},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Distributions — distribution","text":"trans_distr_param Named list transformations distributional parameter. See transform_distr_param list available transformations. location Location parameter. Specifying location parameter necessary distribution used prior distribution. used likelihood component location parameter taken simulated variable fitted data, location parameter left default. sd Standard deviation parameter. disp Dispersion parameter.","code":""},{"path":"https://canmod.github.io/macpan2/reference/distribution.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Distributions — distribution","text":"distributional parameter arguments can specified either numeric value, character string giving parameter name, distributional parameter object (See fit_distr_params).","code":""},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":null,"dir":"Reference","previous_headings":"","what":"Empty Matrix — empty_matrix","title":"Empty Matrix — empty_matrix","text":"Empty matrices useful defining matrices need initialized get computed required expressions. can also provide useful placeholder matrices value certain phase simulation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Empty Matrix — empty_matrix","text":"","code":"empty_matrix"},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Empty Matrix — empty_matrix","text":"numeric matrix zero rows zero columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/empty_matrix.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Empty Matrix — empty_matrix","text":"","code":"spec = mp_tmb_model_spec(during = list(x ~ time_step(0))) identical(spec$empty_matrices()$x, empty_matrix) ## TRUE #> [1] TRUE"},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":null,"dir":"Reference","previous_headings":"","what":"Engine Evaluation — engine_eval","title":"Engine Evaluation — engine_eval","text":"Evaluate expression TMB-based C++ simulation objective function engine. function useful trying engine_functions can used define macpan2 models.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Engine Evaluation — engine_eval","text":"","code":"engine_eval(   .expr,   ...,   .matrix_to_return,   .tmb_cpp = getOption(\"macpan2_dll\"),   .structure_labels = NullLabels() )"},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Evaluation — engine_eval","text":".expr Expression one-sided formula, right-hand-side treated expression evaluated. ... Named objects can coerced numeric matrices. .matrix_to_return Optional name one matrices given ... returned. argument missing, matrix returned matrix returned expression right-hand-side formula. .tmb_cpp Name C++ program defining engine. Typically just want use default, macpan2, unless extending engine . .structure_labels Deprecated.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Engine Evaluation — engine_eval","text":"Matrix produced right-hand-side matrix given .matrix_to_return provided.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_eval.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Evaluation — engine_eval","text":"","code":"engine_eval(~ exp(y), y = pi) # ~ 23.14069 #>          [,1] #> [1,] 23.14069  # It is not currently possible to assign values to a subset of # a matrix in a natural way (e.g. you cannot do things like x[1] = exp(y)), # but you can achieve this functionality using the assign function. engine_eval(~ assign(x, 1, 0, exp(y))   , x = rep(0, 2)   , y = pi   , .matrix_to_return = \"x\" ) #>          [,1] #> [1,]  0.00000 #> [2,] 23.14069"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":null,"dir":"Reference","previous_headings":"","what":"Engine Functions — engine_functions","title":"Engine Functions — engine_functions","text":"Functions currently supported C++ TMB engine constructing expressions defining model simulations.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"quickest way experiment functions use engine_eval function, following example calculates force infection.   produce simulation using engine functions, one may use simple_sims.","code":"engine_eval(~ beta * I / N   , beta = 0.25   , I = 1e3   , N = 1e7 ) simple_sims(   iteration_exprs = list(x ~ x - 0.9 * x),   time_steps = 5,   mats = list(x = 1) )"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"elementwise-binary-operators","dir":"Reference","previous_headings":"","what":"Elementwise Binary Operators","title":"Engine Functions — engine_functions","text":"Elementwise binary operators take two matrix-valued arguments apply binary operator (e.g. +, *) set corresponding elements, return corresponding matrix-valued output containing resulting elements. 'corresponding' mean? two matrix-valued arguments shape (number rows columns), two elements correspond occur row column position two matrices. two matrices shape one row /one column either matrix, singleton rows columns recycled sufficiently many times match shape matrix. recycling singleton rows columns matrices still different shape, error thrown matrices said incompatible.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"x + y x - y x * y x / y x ^ y","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix dimensions compatible y. y – matrix dimensions compatible x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix binary operator applied elementwise necessary recycling rows /columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ 1 + 2) engine_eval(~ y * z, y = 1:3, z = matrix(1:6, 3, 2)) engine_eval(~ 1 / (1 - y), y = 1/4)"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-1","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"log(x) – Natural logarithm exp(x) – Exponential function cos(x) – Cosine function proportions(x, limit, eps) – matrix x / sum(x) rep(limit, length(x)) sum(x) < eps","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-1","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix limit – numeric value return elementwise proportions sum(x) < eps eps – numeric tolerance sum(x)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-1","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix dimensions x, unary function applied elementwise.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-1","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ log(y), y = c(2, 0.5))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-2","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":":– Inclusive ordered sequence integers two bounds. seq(, length, ) – Ordered sequence integers equal spacing adjacent values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-2","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"– Scalar integer giving first integer sequence. – Scalar integer giving last integer sequence. length – Number integers sequence. – Scalar giving difference adjacent values sequence.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-2","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"Column vector sequence integers.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-1","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"colon operator works much like base R version :. takes two scalar-valued integers returns column vector integers two inputs. seq function little different base R default, seq, allows user precise control length output length argument. base R function gives user option, default.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-2","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"Replicate Elements","code":"engine_eval(~ 1:10) engine_eval(~ seq(1, 10, 2))"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-3","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"rep(x, times) – Replicate column vector number times, repeatedly stacking top . rep_each – yet developed. rep_length – yet developed.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-3","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – scalar-valued variable repeat. times – scalar-valued integer variable giving number times repeat x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-3","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"Column vector times copies x stacked top .","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-3","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ rep(1, 10))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-4","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"x %*% y – Standard matrix multiplication. x %x% y – Kronecker product","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-4","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix. standard product, x must many columns y rows. y – matrix. standard product, y must many rows x columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-4","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix product x y.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-4","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ (1:10) %*% t(1:10)) engine_eval(~ (1:10) %x% t(1:10))"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"parenthesis","dir":"Reference","previous_headings":"","what":"Parenthesis","title":"Engine Functions — engine_functions","text":"order operations can enforced usual way round parentheses, (.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-5","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"c(...) – Stack columns arguments single column vector. cbind(...) – Create matrix containing columns group matrices number rows. rbind(...) – Create matrix containing rows group matrices number columns. matrix(x, rows, cols) – Reshape matrix rows rows cols columns. input x must rows * cols elements. t(x) – Standard matrix transpose.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-5","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"... – number dimensionally consistent matrices. definition dimensionally consistent depends function. x – Can matrix t, matrix must rows * cols elements. rows – Scalar integer giving number rows output. cols – Scalar integer giving number columns output.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-5","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"combined reshaped matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-2","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"number column vectors can combined bigger column vector. Column row vectors length can combined using cbind rbind functions respectively matrix function can used redefine numbers rows columns use arranging values matrix. works similarly base R matrix function takes arguments. hand, function differs substantially base R version must filled column byrow option. Matrices can transposed usual function, t.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-5","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ c(a, b, c), a = 1, b = 10:13, c = matrix(20:25, 3, 2)) engine_eval(~ cbind(a, 10 + a), a = 0:3) engine_eval(~ rbind(a, 10 + a), a = t(0:3)) engine_eval(~ matrix(1:12, 4, 3)) engine_eval(~ t(1:3))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-6","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"to_diag(x) – Create diagonal matrix setting diagonal column vector, x. from_diag(x) – Extract diagonal matrix, x, return diagonal column vector.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-6","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix (from_diag) column vector (to_diag). common assume x square from_diag required.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-6","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"to_diag(x) – Diagonal matrix x diagonal. from_diag(x) – Column vector containing diagonal x. value considered diagonal row index equal column index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-3","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"to_diag function can used produce diagonal matrix setting column vector equal desired diagonal. from_diag (almost) opposite, get column vector containing diagonal existing matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-6","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~from_diag(matrix(1:9, 3, 3))) engine_eval(~to_diag(from_diag(matrix(1:9, 3, 3)))) engine_eval(~from_diag(to_diag(from_diag(matrix(1:9, 3, 3)))))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-7","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"sum(...) – Sum elements matrices passed .... col_sums(x) – Row vector containing sums column. row_sums(x) – Column vector containing sums row. group_sums(x, f, n) – Column vector containing sums groups elements x. groups determined integers f order sums output determined integers.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-7","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"... – number matrices shape. x – matrix dimensions, except group_sums expects x column vector. f – column vector length x containing integers 0 m-1, given m unique groups. Elements f refer indices x grouped summed. n – column vector length m. f contain group k [0, m-1], group_sums skips group output index k+1 n[k+1].","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-7","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix containing sums subsets inputs.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-4","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"row_sums col_sums similar base R rowSums colSums functions, slightly different behaviour. particular, row_sums function returns column vector col_sums function returns row vector. specific shape required transpose t function must explicitly used.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-7","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"x = 1 y = 1:3 A = matrix(1:12, 4, 3) engine_eval(~ sum(y), y = y) engine_eval(~ sum(x, y, A), x = x, y = y, A = A) engine_eval(~ col_sums(A), A = A) engine_eval(~ row_sums(A), A = A) engine_eval(~ group_sums(x, f, n), x = 1:10, f = rep(0:3, 1:4), n = c(1:4))"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-8","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"x[,j] – Matrix containing subset rows columns x. block(x,,j,n,m) – Matrix containing contiguous subset rows columns x https://eigen.tuxfamily.org/dox/group__TutorialBlockOperations.html","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-8","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix. – integer column vector ([) integer scalar (block) containing indices rows extract ([) index first row extract (block). j – integer column vector ([) integer scalar (block) containing indices columns extract ([) index first column extract (block). n – Number rows block return. m – Number columns block return.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-8","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix containing subset rows columns x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-5","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"Note zero-based indexing used first row/column gets index, 0, etc.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-8","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"engine_eval(~ A[c(3, 1, 2), 2], A = matrix(1:12, 4, 3)) engine_eval(~ block(x,i,j,n,m), x = matrix(1:12, 4, 3), i=1, j=1, n=2, m=2)"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"accessing-past-values-in-the-simulation-history","dir":"Reference","previous_headings":"","what":"Accessing Past Values in the Simulation History","title":"Engine Functions — engine_functions","text":"matrices simulation history saved, possible bind rows columns past versions matrices single matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-9","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"rbind_lag(x, lag, t_min) – Bind rows versions x recorded end simulation iterations corresponding time lags given integers lag. rbind_time(x, t, t_min) – Bind rows versions x recorded end simulation iterations corresponding integers t. cbind_lag(x, lag, t_min) – Bind columns versions x recorded end simulation iterations corresponding time lags given integers lag. (TODO – cbind_lag developed yet) cbind_time(x, t, t_min) – Bind columns versions x recorded end simulation iterations corresponding integers t. (TODO – cbind_lag developed yet)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-9","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix saved history number columns (rbind_*) rows (cbind_*) change throughout simulation. lag – Integer vector giving numbers time steps current step obtain past values x. t – Integer vector giving time steps obtain past values x. t_min – Integer giving minimum time step allowed accessed. time-steps t implied lag t_min ignored.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-9","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix containing values x past times.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"time-indexing","dir":"Reference","previous_headings":"","what":"Time Indexing","title":"Engine Functions — engine_functions","text":"Get update index current lagged time step index current time group. time group contiguous set time steps defined two change points.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-10","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"time_step(lag): Get time-step associated particular lag current time-step. lagged time-step less zero, function returns zero. time_group(index, change_points): Update index associated current time group. current group defined minimum elements change_points greater current time step. time group index index associated element. Please see examples , easier understand explanation. time_var(x, change_points): improvement time_group. Returns values x time steps change_points, return value remains constant change_points.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-10","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x: Column vector representing time series. time_var return value x corresponding element change_points contains current time. lag: Number time-steps look back time-step return. change_points: Increasing column vector time steps giving lower bound time group.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-10","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"1--1 matrix time-step lag steps ago, zero t+1 < lag","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-9","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"simple_sims(   iteration_exprs = list(x ~ time_step(0)),   time_steps = 10,   mats = list(x = empty_matrix) ) sims = simple_sims(   iteration_exprs = list(     j ~ time_group(j, change_points),     time_varying_parameter ~ time_variation_schedule[j]   ),   mats = list(     j = 0,     change_points = c(0, 4, 7),     time_variation_schedule = c(42, pi, sqrt(2)),     time_varying_parameter = empty_matrix   ),   time_steps = 10, ) set.seed(1L) change_points = c(0,2,5) x_val = rnorm(length(change_points)) simple_sims(     iteration_exprs = list(x ~ time_var(x_val,change_points))   , int_vecs = list(change_points = change_points)   , mats = list(x = empty_matrix, x_val=x_val)   , time_steps = 10 )"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"convolution","dir":"Reference","previous_headings":"","what":"Convolution","title":"Engine Functions — engine_functions","text":"One may take convolution element matrix, x, simulation time using kernel, k. two arguments function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-11","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"convolution(x, k)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-11","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – matrix containing elements convolved. k – column vector giving convolution kernel.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-11","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"matrix size x convolutions, \\(y_{ij}\\), element, \\(x_{ij}\\), given following. $$y_{ij} = \\sum_{\\tau = 0} x_{ij}(t-\\tau) k(\\tau)$$ unless \\(t < \\tau\\), case, $$y_{ij} = $$ \\(y_{ij}\\) convolution, \\(x_{ij}(t)\\) value \\(x_{ij}\\) time step, \\(t\\), \\(k(\\tau)\\) value kernel lag, \\(\\tau\\), \\(\\lambda\\) length kernel.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"details-6","dir":"Reference","previous_headings":"","what":"Details","title":"Engine Functions — engine_functions","text":"empty matrices encountered looking back time, treated matrices zeros. Similarly, matrices encounte x","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"clamp","dir":"Reference","previous_headings":"","what":"Clamp","title":"Engine Functions — engine_functions","text":"Smoothly clamp elements matrix get closer 0 tolerance, eps, default 1e-12. output clamp function follows.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-12","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"clamp(x, eps)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-12","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x : matrix elements remain positive. eps : small positive number giving theoretical minimum elements returned matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"probability-densities","dir":"Reference","previous_headings":"","what":"Probability Densities","title":"Engine Functions — engine_functions","text":"probability densities first two arguments. observed simulated simulated argument gives matrix means observed values densities evaluated. Additional arguments distributional parameters standard deviation dispersion parameter. densities given log-densities, like density must pass result exp function. simulated matrix additional parameter matrices either single row single column, singleton rows columns repeated match number rows columns observed matrix. feature allows one things like specify single common mean several values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-13","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"dpois(observed, simulated) – Log Poisson density based dpois TMB function. dnbinom(observed, simulated, over_dispersion) – Log negative binomial density based dnbinom TMB function. get variance function requires use expression, simulated + simulated^2/over_dispersion, following p.165 book dnorm(observed, simulated, standard_deviation) – Log normal density based dnorm TMB function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-13","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"observed – Matrix observed values density evaluated. simulated – Matrix distributional means, singleton rows columns recycled match numbers rows columns observed. over_dispersion – -dispersion parameter given (simulated/standard_deviation)^2 - simulated). standard_deviation – Standard deviation parameter.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"pseudo-random-number-generators","dir":"Reference","previous_headings":"","what":"Pseudo-Random Number Generators","title":"Engine Functions — engine_functions","text":"random number generator functions mean first argument. Subsequent arguments give additional distributional parameters. Singleton rows columns matrices passed additional distributional parameters recycled arguments number rows columns. functions return matrix shape mean pseudo-random numbers deviating mean mean matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-14","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"rpois(mean) – Pseudo-random Poisson distributed values. rnbinom(mean, over_dispersion) – Pseudo-random negative binomially distributed values. rnorm(mean, standard_deviation) – Pseudo-random normal values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-14","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"mean – Matrix means simulate pseudo-random variation. over_dispersion – Matrix -dispersion parameters given (simulated/standard_deviation)^2 - simulated). standard_deviation – Matrix standard deviation parameters.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"assign","dir":"Reference","previous_headings":"","what":"Assign","title":"Engine Functions — engine_functions","text":"Assign values subset elements matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-15","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"assign(x, , j, v)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-15","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – Matrix elements updated values v. – Column vector row indices pointing elements x updated. indices paired v. length equal v, must single index gets paired every element v. Indices zero-based, =0 corresponds first row. j – Column vector column indices pointing elements x updated. indices paired v. length j equal v, must single index gets paired every element v. Indices zero-based, j=0 corresponds first column. v – Column vector values replace elements x locations given j.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-12","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"assign function called return value, empty_matrix, rather modify x replacing components v.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-10","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"x = matrix(1:12, 3, 4) engine_eval(~ x + 1, x = x) engine_eval(~ x + 1, x = x, .matrix_to_return = \"x\") engine_eval(~ assign(x, 2, 1, 100), x = x, .matrix_to_return = \"x\") engine_eval(~ assign(x   , c(2, 1, 0)   , 0   , c(100, 1000, 10000) ), x = x, .matrix_to_return = \"x\")"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"unpack","dir":"Reference","previous_headings":"","what":"Unpack","title":"Engine Functions — engine_functions","text":"Unpack elements matrix smaller matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-16","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"unpack(x, ...)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-16","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – Matrix elements distributed matrices passed .... ... – Matrices elements replaced values elements x column-major order. matrices must named matrices computed fly using expressions. Note even subsetting (e.g. unpack(x, y[0], y[3])) counts expression. use-case require assign function assign(y, c(0, 3), 0, x).","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-13","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"unpack function called return value, empty_matrix, rather modify matrices ... replacing least components x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-11","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"fill matrix integers 1 12 unpack one---time two column vectors, x y. returning y see integers first three used x.","code":"engine_eval(~unpack(matrix(1:12, 3, 4), x, y)   , x = rep(0, 3)   , y = rep(1, 5)   , .matrix_to_return = \"y\" )"},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"print-matrix","dir":"Reference","previous_headings":"","what":"Print Matrix","title":"Engine Functions — engine_functions","text":"Print value matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"functions-17","dir":"Reference","previous_headings":"","what":"Functions","title":"Engine Functions — engine_functions","text":"print(x)","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"arguments-17","dir":"Reference","previous_headings":"","what":"Arguments","title":"Engine Functions — engine_functions","text":"x – Name matrix model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"return-14","dir":"Reference","previous_headings":"","what":"Return","title":"Engine Functions — engine_functions","text":"empty_matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/engine_functions.html","id":"examples-12","dir":"Reference","previous_headings":"","what":"Examples","title":"Engine Functions — engine_functions","text":"","code":"simple_sims(      list(dummy ~ print(x), x ~ x / 2)    , time_steps = 10    , mats = list(x = 2) )"},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":null,"dir":"Reference","previous_headings":"","what":"Finalizers — finalizer","title":"Finalizers — finalizer","text":"Finalizers","code":""},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Finalizers — finalizer","text":"","code":"finalizer_char(x)  finalizer_index(x)"},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Finalizers — finalizer","text":"x Raw parsed expression.","code":""},{"path":"https://canmod.github.io/macpan2/reference/finalizer.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Finalizers — finalizer","text":"finalizer_char(): Finalize parsed expression parse table little human readable. finalizer_index(): Finalize parsed expression parse table can passed C++ engine.","code":""},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":null,"dir":"Reference","previous_headings":"","what":"Find all Paths — find_all_paths","title":"Find all Paths — find_all_paths","text":"Find paths compartmental model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Find all Paths — find_all_paths","text":"","code":"find_all_paths(edges_df, start_node_guesses = character(0L))"},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Find all Paths — find_all_paths","text":"edges_df data frame column. start_node_guesses Optional guesses nodes start paths. useful models directed acyclic graphs (DAGs).","code":""},{"path":"https://canmod.github.io/macpan2/reference/find_all_paths.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Find all Paths — find_all_paths","text":"List character vectors state variable names, vector describing path model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":null,"dir":"Reference","previous_headings":"","what":"Fitting Distributional Parameters — fit_distr_params","title":"Fitting Distributional Parameters — fit_distr_params","text":"Distributional parameters can added list parameters fit calibration. default, distributional parameters priors likelihoods fit. Use mp_nofit exclude distributional parameters fit mp_fit fit .","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fitting Distributional Parameters — fit_distr_params","text":"","code":"mp_fit(x, trans = DistrParamTransDefault())  mp_nofit(x, trans = DistrParamTransDefault())"},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fitting Distributional Parameters — fit_distr_params","text":"x numeric starting value distributional parameter fit, character name existing variable model default starting value use. trans transformation apply distributional parameter. default, distributional parameters inherit default transformation associated distribution. example, standard deviation parameter sd mp_normal distributions default log transformation specified using mp_log.","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Fitting Distributional Parameters — fit_distr_params","text":"distributional parameter object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/fit_distr_params.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Fitting Distributional Parameters — fit_distr_params","text":"","code":"# First we call the SIR model spec, and generate some data for calibration. spec = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") data = mp_simulator(spec, 50, \"infection\") |> mp_trajectory()  # Suppose we want to specify a Normal prior on the transmission parameter  # beta, and we are interested in estimating the prior standard deviation. # Here we use `mp_fit` to estimate the standard deviation, `sd`, and we  # provide a numeric starting value for `sd` in the optimization.  cal = mp_tmb_calibrator(     spec   , data   , traj = \"infection\"   , par = list(beta = mp_normal(location = 0.35, sd = mp_fit(0.1)))   , default = list(beta = 0.25) )  # When viewing the calibration objective function we can see the additional # prior density term added for beta. The standard deviation parameter has # been automatically named 'distr_params_log_sd_beta'. cal$simulator$tmb_model$obj_fn$obj_fn_expr #> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta,  #>     0.35, exp(distr_params_log_sd_beta))) #> <environment: 0x55c0fbdb67d0>  # Next we optimize and view the fitted parameters. We can see the  # distributional parameter in the coefficient table with a default value  # equal to the numeric value we provided to `mp_fit` above. mp_optimize(cal) #> outer mgc:  379.7835  #> outer mgc:  253.0639  #> outer mgc:  40.08291  #> outer mgc:  1.60249  #> outer mgc:  0.002833777  #> outer mgc:  8.986787e-09  #> $par #>     params     params  #>  0.2005665 -1.9009040  #>  #> $objective #> [1] 49.2679 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 5 #>  #> $evaluations #> function gradient  #>        6        6  #>  #> $message #> [1] \"relative convergence (4)\" #>  mp_tmb_coef(cal) #> outer mgc:  8.986787e-09  #> outer mgc:  11.62005  #> outer mgc:  11.92421  #> outer mgc:  0.0133705  #> outer mgc:  0.01339728  #> outer mgc:  31.09242  #>       term                  mat row col default  type  estimate   std.error #> 1   params                 beta   0   0    0.25 fixed 0.2005665 0.009251899 #> 2 params.1 distr_params_sd_beta   0   0    0.10 fixed 0.1494335 0.106069656  # If instead we want control over the name of the new fitted distributional # parameter, we can add a new variable to our model specification with the  # default value set to the desired optimization starting value. updated_spec = spec |> mp_tmb_insert(default = list(sd_var = 0.1))  # In the calibrator, we use the name of this newly added variable, \"sd_var\", # as input to `mp_fit`. cal = mp_tmb_calibrator(     updated_spec   , data   , traj = \"infection\"   , par = list(beta = mp_normal(location = 0.35, sd = mp_fit(\"sd_var\")))   , default = list(beta = 0.25) )  # We can see this distributional parameter get propogated to the objective  # function and the fitted parameter table. cal$simulator$tmb_model$obj_fn$obj_fn_expr #> ~-sum(dpois(obs_infection, clamp(sim_infection))) - sum(dnorm(beta,  #>     0.35, exp(sd_var))) #> <environment: 0x55c0fb9bfd58> mp_optimize(cal) #> outer mgc:  389.7016  #> outer mgc:  258.9379  #> outer mgc:  42.94112  #> outer mgc:  2.418362  #> outer mgc:  0.01416442  #> outer mgc:  7.421077e-06  #> outer mgc:  3.974682e-12  #> $par #>     params     params  #>  0.2005665 -1.9009040  #>  #> $objective #> [1] 49.2679 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 6 #>  #> $evaluations #> function gradient  #>        7        7  #>  #> $message #> [1] \"relative convergence (4)\" #>  mp_tmb_coef(cal) #> outer mgc:  3.974682e-12  #> outer mgc:  11.62005  #> outer mgc:  11.92421  #> outer mgc:  0.01337051  #> outer mgc:  0.01339727  #> outer mgc:  31.09242  #>       term    mat row col default  type   estimate   std.error #> 1   params   beta   0   0    0.25 fixed  0.2005665 0.009251899 #> 2 params.1 sd_var   0   0    0.10 fixed -1.9009040 0.709811879"},{"path":"https://canmod.github.io/macpan2/reference/initial_valid_vars.html","id":null,"dir":"Reference","previous_headings":"","what":"Initial Valid Variables — initial_valid_vars","title":"Initial Valid Variables — initial_valid_vars","text":"Initial Valid Variables","code":""},{"path":"https://canmod.github.io/macpan2/reference/initial_valid_vars.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Initial Valid Variables — initial_valid_vars","text":"","code":"initial_valid_vars(valid_var_names)"},{"path":"https://canmod.github.io/macpan2/reference/initial_valid_vars.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Initial Valid Variables — initial_valid_vars","text":"valid_var_names Character vector variable names.","code":""},{"path":"https://canmod.github.io/macpan2/reference/macpan2-package.html","id":null,"dir":"Reference","previous_headings":"","what":"macpan2 — macpan2-package","title":"macpan2 — macpan2-package","text":"R package -McMasterPandemic package compartmental epidemic modelling forecasting analysis infectious diseases.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/macpan2-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"macpan2 — macpan2-package","text":"Maintainer: Steve Walker swalk@mcmaster.ca Authors: Weiguang Guan Jen Freeman Ben Bolker Darren Flynn-Primrose contributors: Irena Papst [contributor] Michael Li [contributor]","code":""},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate an Arithmetic Expression Parser — make_expr_parser","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"Generate Arithmetic Expression Parser","code":""},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"","code":"make_expr_parser(parser_name = NULL, finalizer = force)"},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"parser_name Name parsing function character string. longer used, still present back-compatibility. finalizer Function used post-process parsed formula. default identity finalizer, returns parsed formula .  good choices finalizer_char, can used understand formula parsed, finalizer_index, can passed C++ engine. result function another function takes single argument, x.  resulting function recursive.  x argument one-sided formula first time recursive function called.  subsequent evaluations recursion, x list following structure.  x formula, must contain named list functions called valid_funcs named list variables called valid_vars. x list names numeric objects represent leaf parse tree n integer vector length x give number arguments associated functions x 0 otherwise index identifying element x corresponding first argument associated function 0 function valid_funcs named list valid functions extracted environment formula parsed valid_vars named list default values valid variables extracted environment formula parsed input_expr_as_string input formula stored string","code":""},{"path":"https://canmod.github.io/macpan2/reference/make_expr_parser.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generate an Arithmetic Expression Parser — make_expr_parser","text":"","code":"parser = make_expr_parser(finalizer = finalizer_char) foi = ~ beta * I / 100 valid_funcs = setNames(   list(`*`, `/`),   c(\"*\", \"/\") ) valid_vars = list(beta = 0.1, I = 30) parser(foi) #>      x n i #> 1    ~ 1 1 #> 2    / 2 2 #> 3    * 2 4 #> 4  100 0 0 #> 5 beta 0 0 #> 6    I 0 0"},{"path":"https://canmod.github.io/macpan2/reference/mp_aggregate.html","id":null,"dir":"Reference","previous_headings":"","what":"Aggregate an Index — mp_aggregate","title":"Aggregate an Index — mp_aggregate","text":"Create one-column ledger (see LedgerDefinition) rows identifying instances aggregation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_aggregate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Aggregate an Index — mp_aggregate","text":"","code":"mp_aggregate(index, by = \"Group\", ledger_column = \"group\")"},{"path":"https://canmod.github.io/macpan2/reference/mp_aggregate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Aggregate an Index — mp_aggregate","text":"index index aggregate . column set label group . default dummy constant \"Group\" column created. ledger_column Name column output ledger describes groups.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":null,"dir":"Reference","previous_headings":"","what":"Cartesian Product of Index Tables — mp_cartesian","title":"Cartesian Product of Index Tables — mp_cartesian","text":"Produce new index table taking possible pairwise combinations input tables. useful producing product models expand model components stratification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cartesian Product of Index Tables — mp_cartesian","text":"","code":"mp_cartesian(...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cartesian Product of Index Tables — mp_cartesian","text":"... Index tables (see mp_index).","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_cartesian.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Cartesian Product of Index Tables — mp_cartesian","text":"","code":"mp_cartesian(   mp_index(Epi = c(\"S\", \"I\")),   mp_index(Age = c(\"young\", \"old\")) ) #>  Epi   Age #>    S young #>    I young #>    S   old #>    I   old  si = mp_index(Epi = c(\"S\", \"I\")) age = mp_index(Age = c(\"young\", \"old\")) loc = mp_index(City = c(\"hamilton\", \"toronto\")) vax = mp_index(Vax = c(\"unvax\", \"vax\")) (si   |> mp_cartesian(age)   |> mp_cartesian(loc)   |> mp_cartesian(vax) ) #>  Epi   Age     City   Vax #>    S young hamilton unvax #>    I young hamilton unvax #>    S   old hamilton unvax #>    I   old hamilton unvax #>    S young  toronto unvax #>    I young  toronto unvax #>    S   old  toronto unvax #>    I   old  toronto unvax #>    S young hamilton   vax #>    I young hamilton   vax #>    S   old hamilton   vax #>    I   old hamilton   vax #>    S young  toronto   vax #>    I young  toronto   vax #>    S   old  toronto   vax #>    I   old  toronto   vax  flow_rates = mp_index(Epi = c(\"infection\", \"recovery\")) mp_union(   mp_cartesian(     mp_subset(flow_rates, Epi = \"infection\"),     age   ),   mp_subset(flow_rates, Epi = \"recovery\") ) #>        Epi   Age #>  infection young #>  infection   old #>   recovery"},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":null,"dir":"Reference","previous_headings":"","what":"Default Values — mp_default","title":"Default Values — mp_default","text":"Default Values","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Default Values — mp_default","text":"","code":"mp_default(model)  mp_default_list(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Default Values — mp_default","text":"model model object extract default values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Default Values — mp_default","text":"long-format data frame default values matrices required input model objects. columns output matrix, row, col, value. Scalar matrices entries row col columns.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_default.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Default Values — mp_default","text":"mp_default_list(): List default variables matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_model.html","id":null,"dir":"Reference","previous_headings":"","what":"Dynamic Model — mp_dynamic_model","title":"Dynamic Model — mp_dynamic_model","text":"'old' model specification function tested workshop. Currently still drives engine-agnostic-grammar vignette, plan replace function mp_tmb_model_spec model specification functions.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_model.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Dynamic Model — mp_dynamic_model","text":"","code":"mp_dynamic_model(   expr_list = ExprList(),   ledgers = list(),   init_vecs = list(),   unstruc_mats = list() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_model.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Dynamic Model — mp_dynamic_model","text":"expr_list Expression list. ledgers Ledgers. init_vecs Initial structured vectors. unstruc_mats Initial unstructured matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_simulator.html","id":null,"dir":"Reference","previous_headings":"","what":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","title":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","text":"'old' function tested workshop. Currently still drives engine-agnostic-grammar vignette, plan replace function mp_simulator.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_simulator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","text":"","code":"mp_dynamic_simulator(   dynamic_model,   time_steps = 0L,   vectors = NULL,   unstruc_mats = NULL,   mats_to_save = NULL,   mats_to_return = NULL,   params = OptParamsList(0),   random = OptParamsList(),   obj_fn = ObjectiveFunction(~0),   log_file = LogFile(),   do_pred_sdreport = TRUE,   tmb_cpp = \"macpan2\",   initialize_ad_fun = TRUE,   ... )"},{"path":"https://canmod.github.io/macpan2/reference/mp_dynamic_simulator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"TMB Simulator from Dynamic Model — mp_dynamic_simulator","text":"dynamic_model Object product mp_dynamic_model. time_steps Number time steps simulate. vectors Named list named vectors initial values simulations referenced expression list dynamic model. unstruc_mats = Named list objects can coerced numerical matrices used expression list dynamic model. mats_to_save TODO mats_to_return TODO params TODO random TODO obj_fn TODO log_file TODO do_pred_sdreport TODO tmb_cpp TODO initialize_ad_fun TODO ... TODO","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":null,"dir":"Reference","previous_headings":"","what":"Describe Statistical Effects — mp_effects_descr","title":"Describe Statistical Effects — mp_effects_descr","text":"Additional information can joined output tidy.TMB tidy.stanfit functions broom.mixed package.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Describe Statistical Effects — mp_effects_descr","text":"","code":"mp_effects_descr(model)  mp_add_effects_descr(coef_table, model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Describe Statistical Effects — mp_effects_descr","text":"model model TMB engine can used compute tables statistical effects. coef_table Coefficient table probably generated using mp_tmb_coef mp_tmbstan_coef, also perhaps generated directly using tidy.TMB tidy.stanfit methods broom.mixed package.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_effects_descr.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Describe Statistical Effects — mp_effects_descr","text":"mp_add_effects_descr(): Convenience function adding coefficient descriptions calibrated model coef_tables generated mp_tmb_coef mp_tmbstan_coef.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":null,"dir":"Reference","previous_headings":"","what":"State Updates — mp_euler","title":"State Updates — mp_euler","text":"Use functions update model spec state variables updated according different numerical methods.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"State Updates — mp_euler","text":"","code":"mp_euler(model)  mp_rk4(model)  mp_euler_multinomial(model)  mp_hazard(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"State Updates — mp_euler","text":"model Object quantities explicitly marked state variables.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"State Updates — mp_euler","text":"default update method model specifications produced using mp_tmb_model_spec mp_euler. update method yields difference-equation model state updated per time-step using absolute flow rate difference steps. state update functions used modify model specification use particular kind state update. see modified models particular example one may use mp_expand function (see examples).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"State Updates — mp_euler","text":"mp_rk4(): ODE solver using Runge-Kutta 4. formulas appear model flows list updated RK4 contain functions getOption(\"macpan2_non_iterable_funcs\") make state variable assignments (.e., left-hand-side contain state variables). formula meet conditions evaluated time-step three RK4 iterations taken. default, time_var function functions generate random numbers (e.g., rbinom) iterable. Functions generate random numbers called state update methods repeat expressions per time-step (e.g., mp_euler), repeating functions RK4 make difficult compare methods. really want regenerate random numbers RK4 iteration, can setting option appropriately. time_var function assumes called per time-step, never removed list non-iterable functions. Although principle make sense update state variables manually, currently causes us confused. therefore require state variables updates set explicitly (e.g., mp_per_capita_flow) explicit. mp_euler_multinomial(): Update state process error given Euler-multinomial distribution. mp_hazard(): Update state hazard steps, equivalent taking step given expected value Euler-multinomial distribution.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_euler.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"State Updates — mp_euler","text":"","code":"sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") sir #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #>  sir |> mp_euler()             |> mp_expand() #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ S * (I * beta/N) #> 2: recovery ~ I * (gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>  sir |> mp_rk4()               |> mp_expand() #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #>  1: infection ~ S * (I * beta/N) #>  2: recovery ~ I * (gamma) #>  3: k1_S ~ -infection #>  4: k1_I ~ +infection - recovery #>  5: k1_R ~ +recovery #>  6: infection ~ (S + (k1_S/2)) * ((I + (k1_I/2)) * beta/N) #>  7: recovery ~ (I + (k1_I/2)) * (gamma) #>  8: k2_S ~ -infection #>  9: k2_I ~ +infection - recovery #> 10: k2_R ~ +recovery #> 11: infection ~ (S + (k2_S/2)) * ((I + (k2_I/2)) * beta/N) #> 12: recovery ~ (I + (k2_I/2)) * (gamma) #> 13: k3_S ~ -infection #> 14: k3_I ~ +infection - recovery #> 15: k3_R ~ +recovery #> 16: infection ~ (S + k3_S) * ((I + k3_I) * beta/N) #> 17: recovery ~ (I + k3_I) * (gamma) #> 18: k4_S ~ -infection #> 19: k4_I ~ +infection - recovery #> 20: k4_R ~ +recovery #> 21: S ~ S + (k1_S + 2 * k2_S + 2 * k3_S + k4_S)/6 #> 22: I ~ I + (k1_I + 2 * k2_I + 2 * k3_I + k4_I)/6 #> 23: R ~ R + (k1_R + 2 * k2_R + 2 * k3_R + k4_R)/6 #>  sir |> mp_euler_multinomial() |> mp_expand() #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ reulermultinom(S, (I * beta/N)) #> 2: recovery ~ reulermultinom(I, gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":null,"dir":"Reference","previous_headings":"","what":"Expand Model — mp_expand","title":"Expand Model — mp_expand","text":"Expand structured model represented unstructured format requiring verbose description. Currently, applicable mp_tmb_model_spec objects explicit flows (e.g. mp_per_capita_flow). models, mp_expand produces model expression lists composed entirely plain R formulas.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Expand Model — mp_expand","text":"","code":"mp_expand(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Expand Model — mp_expand","text":"model model object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_expand.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Expand Model — mp_expand","text":"","code":"sir = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") print(sir) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = infection ~ I *  #>      beta/N) #> 2: mp_per_capita_flow(from = \"I\", to = \"R\", rate = recovery ~ gamma) #>  print(mp_expand(sir)) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>    beta           0.2 #>   gamma           0.1 #>       N         100.0 #>       I           1.0 #>       R           0.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - I - R #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ S * (I * beta/N) #> 2: recovery ~ I * (gamma) #> 3: S ~ S - infection #> 4: I ~ I + infection - recovery #> 5: R ~ R + recovery #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_extract.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract Index — mp_extract","title":"Extract Index — mp_extract","text":"Extract index particular dimension ledger ledger object containing one ledgers.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_extract.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract Index — mp_extract","text":"","code":"mp_extract(x, dimension_name)"},{"path":"https://canmod.github.io/macpan2/reference/mp_extract.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract Index — mp_extract","text":"x Object dimension_name Name dimension used ledger.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_factors.html","id":null,"dir":"Reference","previous_headings":"","what":"Factor an Index — mp_factors","title":"Factor an Index — mp_factors","text":"Factor Index","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_factors.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Factor an Index — mp_factors","text":"","code":"mp_factors(index, unpack = c(\"no\", \"maybe\", \"yes\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_factors.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Factor an Index — mp_factors","text":"index index factored. unpack Place factors global environment?","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":null,"dir":"Reference","previous_headings":"","what":"Final Values — mp_final","title":"Final Values — mp_final","text":"Return values variables simulation loop finished final set expressions evaluated.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Final Values — mp_final","text":"","code":"mp_final(model)  mp_final_list(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Final Values — mp_final","text":"model Object can used simulate.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_final.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Final Values — mp_final","text":"mp_final_list(): Final values formatted list matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow Frame (experimental) — mp_flow_frame","title":"Flow Frame (experimental) — mp_flow_frame","text":"Get data frame representing flows model specification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow Frame (experimental) — mp_flow_frame","text":"","code":"mp_flow_frame(spec, topological_sort = TRUE, loops = \"^$\")"},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow Frame (experimental) — mp_flow_frame","text":"spec mp_tmb_model_spec. topological_sort states topologically sorted respect main direction flow? loops Pattern matching names flows make flow model DAG, critical assumption topologically sorting order states flows output. relevant topological_sort used.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_flow_frame.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Flow Frame (experimental) — mp_flow_frame","text":"data frame gives information provided calls mp_per_capita_flow mp_per_capita_inflow.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_group.html","id":null,"dir":"Reference","previous_headings":"","what":"Group an Index — mp_group","title":"Group an Index — mp_group","text":"Create new index fewer columns create names aggregated vector labelled input index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_group.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Group an Index — mp_group","text":"","code":"mp_group(index, by)"},{"path":"https://canmod.github.io/macpan2/reference/mp_group.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Group an Index — mp_group","text":"index Index group rows. Column set label group .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":null,"dir":"Reference","previous_headings":"","what":"Model Quantity Index Table — mp_index","title":"Model Quantity Index Table — mp_index","text":"Make index table enumerate model quantity labels category. objects generalize wrap data.frames, column label category row index. Indices must contain letters, numbers, underscores. Blank empty string entries allowed, missing values (NAs) .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model Quantity Index Table — mp_index","text":"","code":"mp_index(..., labelling_column_names)  # S3 method for class 'Index' print(x, ...)  # S3 method for class 'Index' names(x)  # S3 method for class 'Index' labelling_column_names(x)  # S3 method for class 'Index' labels(object, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model Quantity Index Table — mp_index","text":"... Character vectors combine produce index. Alternatively, number data frames character-valued columns. data frames supplied, rows bound result converted index possible. labelling_column_names character vector names index used label model components (.e. rows) described. labelling_column_names duplicates must contain least one name. index given labelling_column_names must uniquely identify row. default NULL gives set columns, order starting first column, required uniquely identify row. x index. object index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Model Quantity Index Table — mp_index","text":"example, following index table describes state variables model:   , column Epi denotes category labels epidemiological. nothing special specific choice category name; also used another name like Compartment. However, complicated models, good think carefully choosing descriptive category names. example, age-structured SIR model, add Age column generate index table follows:   , first column index table labeled Compartment somewhat misleading, compartments actually just \"S\", \"\", \"R\", epidemiological states stratified age groups \"young\" \"old\". index table also generated first specifying individual index tables Epi Age columns, using macpan2 product function combines tables single index table:   mp_cartesian() function produce table entries possible combinations individual index tables. \"See Also\" section mp_cartesian() help page catalogues available product functions. can produce full labels model quantities, simply dot-concatenated indices, one entry index table, using labels() function:   Dots allowed indices labels can inverted reproduce original index table (provided column names can retrieved). recommended use UpperCamelCase columns index tables single uppercase characters (\"S\", \"\"), lowercase character strings (\"gamma\"), /snake_case strings (\"aging_rate\") indices. convention helps reading code contains references column names indices.","code":"sir = mp_index(Epi = c(\"S\", \"I\", \"R\")) print(sir) #>  Epi #>    S #>    I #>    R sir_age = mp_index(  Epi = rep(c(\"S\", \"I\", \"R\"), 2),  Age = rep(c(\"young\", \"old\"), each = 3) ) print(sir_age) #>  Epi   Age #>    S young #>    I young #>    R young #>    S   old #>    I   old #>    R   old sir = mp_index(Epi = c(\"S\", \"I\", \"R\")) age = mp_index(Age = c(\"young\", \"old\")) prod = mp_cartesian(sir, age) prod #>  Epi   Age #>    S young #>    I young #>    R young #>    S   old #>    I   old #>    R   old #> [1] \"S.young\" \"I.young\" \"R.young\" \"S.old\"   \"I.old\"   \"R.old\""},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Model Quantity Index Table — mp_index","text":"print(Index): Print index. names(Index): Get names columns index. labelling_column_names(Index): Retrieve labelling_column_names index. names columns used label model components. labels(Index): Convert index character vector giving labels associated model component (.e. row) described.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_index.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Model Quantity Index Table — mp_index","text":"","code":"state = mp_index(   Epi = c(\"S\", \"I\", \"S\", \"I\"),   Age = c(\"young\", \"young\", \"old\", \"old\") ) print(state) #>  Epi   Age #>    S young #>    I young #>    S   old #>    I   old labels(state) #> [1] \"S.young\" \"I.young\" \"S.old\"   \"I.old\"   mp_cartesian(state, mp_index(City = c(\"hamilton\", \"toronto\"))) #>  Epi   Age     City #>    S young hamilton #>    I young hamilton #>    S   old hamilton #>    I   old hamilton #>    S young  toronto #>    I young  toronto #>    S   old  toronto #>    I   old  toronto"},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":null,"dir":"Reference","previous_headings":"","what":"Initial Values — mp_initial","title":"Initial Values — mp_initial","text":"Return data frame containing values variables end phase, right simulation loop begins (.e. right phase).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Initial Values — mp_initial","text":"","code":"mp_initial(model)  mp_initial_list(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Initial Values — mp_initial","text":"model model specification object model simulator object extract initial values.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Initial Values — mp_initial","text":"long-format data frame initial values matrices. columns output matrix, time, row, col, value. Scalar matrices entries row col columns. phase corresponds time value 0.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_initial.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Initial Values — mp_initial","text":"mp_initial_list(): List initial variables matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":null,"dir":"Reference","previous_headings":"","what":"Join Indexes — mp_join","title":"Join Indexes — mp_join","text":"Join two index tables (see mp_index) produce ledger (see LedgerDefinition).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Join Indexes — mp_join","text":"","code":"mp_join(..., by = empty_named_list())"},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Join Indexes — mp_join","text":"... Named arguments giving indexes created mp_index another function manipulates indexes. argument become position vector used subset expand numeric vectors archetype formulas. columns use join indexes. See specify argument.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_join.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Join Indexes — mp_join","text":"two index tables passed ..., mp_join behaves much like ordinary inner join. two tables passed ..., mp_join iteratively joins pairs tables produce final ledger. example, index tables B, C passed mp_join, inner join B performed result joined C. successive internal joins. properties inner joins ensures order tables affect set rows final table (SW states without proof!). two index tables passed ..., argument just character vector column names join (standard R functions joining data frames), dot-concatenation column names. example,   two tables argument must named list character vectors, describing join columns pair tables .... names list dot-concatenations names pairs tables .... example,   columns different names two tables, can specify using formula notation left-hand-side dot-concatenation columns first table right-hand-side dot-concatenation columns second table. example,","code":"state = mp_index(   Epi = c(\"S\", \"I\", \"S\", \"I\"),   Age = c(\"young\", \"young\", \"old\", \"old\") ) mp_join(   from = mp_subset(state, Epi = \"S\"),   to = mp_subset(state, Epi = \"I\"),   by = \"Age\" ) #>     from      to #>  S.young I.young #>    S.old   I.old rates = mp_index(   Epi = c(\"lambda\", \"lambda\"),   Age = c(\"young\", \"old\") ) mp_join(   from = mp_subset(state, Epi = \"S\"),   to = mp_subset(state, Epi = \"I\"),   rate = mp_subset(rates, Epi = \"lambda\"),   by = list(     from.to = \"Age\",     from.rate = \"Age\"   ) ) #>     from      to         rate #>  S.young I.young lambda.young #>    S.old   I.old   lambda.old contact = mp_index(   AgeSusceptible = c(\"young\", \"young\", \"old\", \"old\"),   AgeInfectious = c(\"young\", \"old\", \"young\", \"old\") ) mp_join(   sus = mp_subset(state, Epi = \"S\"),   inf = mp_subset(state, Epi = \"I\"),   con = contact,   by = list(     sus.con = \"Age\" ~ \"AgeSusceptible\",     inf.con = \"Age\" ~ \"AgeInfectious\"   ) ) #>      sus     inf         con #>  S.young I.young young.young #>    S.old I.young   old.young #>  S.young   I.old   young.old #>    S.old   I.old     old.old"},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Index Labels — mp_labels","title":"Index Labels — mp_labels","text":"Return character vector labels row index (ledger?? FIXME: mean ledgers??).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Index Labels — mp_labels","text":"","code":"mp_labels(x, labelling_column_names)"},{"path":"https://canmod.github.io/macpan2/reference/mp_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Index Labels — mp_labels","text":"x Object labelling_column_names index columns used generating labels. missing defaults used. (FIXME: clarify defaults used.)","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_grid.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow Diagram Grid Layout — mp_layout_grid","title":"Flow Diagram Grid Layout — mp_layout_grid","text":"Create grid layout flow diagram model specification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_grid.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow Diagram Grid Layout — mp_layout_grid","text":"","code":"mp_layout_grid(   spec,   east = \"\",   south = \"^$\",   north = \"^$\",   west = \"^$\",   loops = north,   x_gap = 0.3,   y_gap = 0.3,   north_south_sep = 0,   east_west_sep = 0,   trim_states = character() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_grid.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow Diagram Grid Layout — mp_layout_grid","text":"spec model specification made mp_tmb_model_spec related function. east Regular expression matching names flows connected eastward layout. south Regular expression matching names flows connected southward layout. north Regular expression matching names flows connected northward layout. west Regular expression matching names flows connected westward layout. loops Regular expression matching names flows cause loops flow model, ignored building layout. x_gap Size gap left right 1--1 space provided node. y_gap Size gap 1--1 space provided node. north_south_sep Horizontal separation north south flow arrows. east_west_sep Vertical separation east west flow arrows. trim_states List states remove diagram","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_paths.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow Diagram Grid Layout — mp_layout_paths","title":"Flow Diagram Grid Layout — mp_layout_paths","text":"Layout flow diagram model specification row one paths model (ignoring loops).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_paths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow Diagram Grid Layout — mp_layout_paths","text":"","code":"mp_layout_paths(   spec,   sort_paths = TRUE,   combine_columns = TRUE,   deduplicate_edges = TRUE,   loops = \"^$\",   ignore = \"^$\",   x_gap = 0.3,   y_gap = 0.3,   north_south_sep = 0,   east_west_sep = 0,   trim_states = character() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_layout_paths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow Diagram Grid Layout — mp_layout_paths","text":"spec model specification made mp_tmb_model_spec related function. sort_paths paths/rows sorted minimize number times edge must go node connected ? combine_columns state/node get column layout (FALSE) algorithm try place branching states column (TRUE, default). deduplicate_edges row edges path duplicate edges removed? loops Regular expression matching names flows cause loops flow model, ignored building layout. ignore Regular expression matching names flows removed layout analysis entirely. isolated data frame custom drawing 'difficult' edges. x_gap Size gap left right 1--1 space provided node. y_gap Size gap 1--1 space provided node. north_south_sep Horizontal separation north south flow arrows. east_west_sep Vertical separation east west flow arrows. trim_states List states remove diagram","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_ledgers.html","id":null,"dir":"Reference","previous_headings":"","what":"Bundle up Ledgers — mp_ledgers","title":"Bundle up Ledgers — mp_ledgers","text":"Bundle several ledgers (see LedgerDefinition) pass mp_dynamic_model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_ledgers.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Bundle up Ledgers — mp_ledgers","text":"","code":"mp_ledgers(...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_ledgers.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Bundle up Ledgers — mp_ledgers","text":"... Ledgers bundle .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_linear.html","id":null,"dir":"Reference","previous_headings":"","what":"Linear Chain Product — mp_linear","title":"Linear Chain Product — mp_linear","text":"TODO: mean?","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_linear.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Linear Chain Product — mp_linear","text":"","code":"mp_linear(x, y_labelling_column_names)"},{"path":"https://canmod.github.io/macpan2/reference/mp_linear.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Linear Chain Product — mp_linear","text":"x index. y_labelling_column_names TODO","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_lookup.html","id":null,"dir":"Reference","previous_headings":"","what":"Lookup — mp_lookup","title":"Lookup — mp_lookup","text":"Lookup subset factor index associated symbol, return index associated symbol.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_lookup.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Lookup — mp_lookup","text":"","code":"mp_lookup(index, symbol)"},{"path":"https://canmod.github.io/macpan2/reference/mp_lookup.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Lookup — mp_lookup","text":"index Index table (see mp_index). symbol Character string possibly associated subset factor index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_model_starter.html","id":null,"dir":"Reference","previous_headings":"","what":"Model Starter — mp_model_starter","title":"Model Starter — mp_model_starter","text":"Create directory template model definition.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_model_starter.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model Starter — mp_model_starter","text":"","code":"mp_model_starter(starter_name, dir)"},{"path":"https://canmod.github.io/macpan2/reference/mp_model_starter.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model Starter — mp_model_starter","text":"starter_name Currently can sir. dir String giving path directory copying template model definition.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":null,"dir":"Reference","previous_headings":"","what":"Optimize — mp_optimize","title":"Optimize — mp_optimize","text":"Optimize","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Optimize — mp_optimize","text":"","code":"mp_optimize(model, optimizer, ...)  # S3 method for class 'TMBCalibrator' mp_optimize(model, optimizer = c(\"nlminb\", \"optim\"), ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Optimize — mp_optimize","text":"model model object capable optimized. See model types supported. optimizer Name implemented optimizer. See options type model. ... Arguments pass optimizer.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Optimize — mp_optimize","text":"output optimizer. model object modified saves history optimization outputs. outputs can obtained using mp_optimizer_output.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimize.html","id":"methods-by-class-","dir":"Reference","previous_headings":"","what":"Methods (by class)","title":"Optimize — mp_optimize","text":"mp_optimize(TMBCalibrator): Optimize TMB calibrator.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":null,"dir":"Reference","previous_headings":"","what":"Optimizer Output — mp_optimizer_output","title":"Optimizer Output — mp_optimizer_output","text":"Get output optimizer used model calibration.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Optimizer Output — mp_optimizer_output","text":"","code":"mp_optimizer_output(model, what = c(\"latest\", \"all\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Optimizer Output — mp_optimizer_output","text":"model object optimized. string indicating whether return results \"latest\" optimization attempt list \"\" .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_optimizer_output.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Optimizer Output — mp_optimizer_output","text":"objects created mp_tmb_calibrator successfully passed mp_optimize, build optimization history. history recorded list output produced underlying optimizer (e.g. nlminb). mp_optimizer_output function returns latest output default entire history list.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_par.html","id":null,"dir":"Reference","previous_headings":"","what":"Fit Parameters — mp_par","title":"Fit Parameters — mp_par","text":"Define prior distributions parameters random effects passed par argument mp_tmb_calibrator function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_par.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fit Parameters — mp_par","text":"","code":"mp_par(param, random)"},{"path":"https://canmod.github.io/macpan2/reference/mp_par.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fit Parameters — mp_par","text":"param Named list distributional specifications fixed effects. random Named list distributional specifications random effects.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":null,"dir":"Reference","previous_headings":"","what":"Flow — mp_per_capita_flow","title":"Flow — mp_per_capita_flow","text":"Specify different kinds flows compartments.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Flow — mp_per_capita_flow","text":"","code":"mp_per_capita_flow(from, to, rate, abs_rate = NULL)  mp_per_capita_inflow(from, to, rate, abs_rate = NULL)  mp_per_capita_outflow(from, rate, abs_rate = NULL)  mp_absolute_flow(from, to, rate, rate_name = NULL)"},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Flow — mp_per_capita_flow","text":"String giving name compartment flow originates. String giving name compartment flow going. rate String giving expression per-capita absolute flow rate. Alternatively per-capita flows, back compatibility, two-sided formula left-hand-side giving name absolute flow rate per unit time-stepand right-hand-side giving expression per-capita rate flow . abs_rate String giving name absolute flow rate, computed * rate. formula passed rate (recommended), abs_rate argument ignored. rate_name String giving name absolute flow rate.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Flow — mp_per_capita_flow","text":"examples can mixed matched mp_tmb_model_spec() produce compartmental models. Note symbols used must used appropriate context (e.g., N used total population size, must expression like N ~ S + + R somewhere model models constant population size must default variable, N, numerical value).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Flow — mp_per_capita_flow","text":"mp_per_capita_inflow(): flow compartment, flow compartment. compartment can even function set compartments, updated. common construction mp_per_capita_inflow(\"N\", \"S\", \"birth_rate\", \"birth\") adding birth process, involves total population size, N, rather single compartment. mp_per_capita_outflow(): flow compartment, without going anywhere. useful removing individuals system (e.g., death). keep track total number dead individuals one can use mp_per_capita_flow set compartment individuals (e.g., = \"D\"). mp_absolute_flow(): Experimental","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_per_capita_flow.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Flow — mp_per_capita_flow","text":"","code":"# infection by mass action # https://github.com/canmod/macpan2/blob/main/inst/starter_models/si mp_per_capita_flow(\"S\", \"I\", \"beta * I / N\", \"infection\") #> From: S #> To: I #> Per-capita rate expression: beta * I/N #> Absolute rate symbol: infection  # recovery # https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir mp_per_capita_flow(\"I\", \"R\", \"gamma\", \"recovery\") #> From: I #> To: R #> Per-capita rate expression: gamma #> Absolute rate symbol: recovery  # disease progression with different severity # https://github.com/canmod/macpan2/blob/main/inst/starter_models/macpan_base mp_per_capita_flow(\"E\", \"I_mild\", \"alpha * phi\"      , \"progression_mild\") #> From: E #> To: I_mild #> Per-capita rate expression: alpha * phi #> Absolute rate symbol: progression_mild mp_per_capita_flow(\"E\", \"I_sev\" , \"alpha * (1 - phi)\", \"progression_sev\") #> From: E #> To: I_sev #> Per-capita rate expression: alpha * (1 - phi) #> Absolute rate symbol: progression_sev  # birth # https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir_demog mp_per_capita_inflow(\"N\", \"S\", \"nu\", \"birth\") #> From: N #> To: S #> Per-capita rate expression: nu #> Absolute rate symbol: birth  # death # https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir_demog mp_per_capita_outflow(\"S\", \"mu\", \"death_S\") #> From: S #> Per-capita rate expression: mu #> Absolute rate symbol: death_S mp_per_capita_outflow(\"I\", \"mu\", \"death_I\") #> From: I #> Per-capita rate expression: mu #> Absolute rate symbol: death_I mp_per_capita_outflow(\"R\", \"mu\", \"death_R\") #> From: R #> Per-capita rate expression: mu #> Absolute rate symbol: death_R  # vaccination  # https://github.com/canmod/macpan2/blob/main/inst/starter_models/shiver mp_per_capita_flow(\"S\", \"V\", \"((a * S)/(b + S))/S\",  \"vaccination\") #> From: S #> To: V #> Per-capita rate expression: ((a * S)/(b + S))/S #> Absolute rate symbol: vaccination  # importation (experimental) # mp_absolute_inflow(\"I\", \"delta\", \"importation\")"},{"path":"https://canmod.github.io/macpan2/reference/mp_positions.html","id":null,"dir":"Reference","previous_headings":"","what":"Position Vectors — mp_positions","title":"Position Vectors — mp_positions","text":"Return integer vector positions x table. Currently simple wrapper around match.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_positions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Position Vectors — mp_positions","text":"","code":"mp_positions(x, table, zero_based = TRUE)"},{"path":"https://canmod.github.io/macpan2/reference/mp_positions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Position Vectors — mp_positions","text":"x Character vector table Character vector zero_based Use zero-based indexing? Defaults TRUE, otherwise standard R one-based indexing used.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rbf.html","id":null,"dir":"Reference","previous_headings":"","what":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","title":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","text":"Pass output function tv argument mp_tmb_calibrator model time variation parameter flexible radial basis functions.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rbf.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","text":"","code":"mp_rbf(   tv,   dimension,   initial_weights,   seed,   prior_sd = 1,   fit_prior_sd = TRUE,   sparse_tol = 0.01 )"},{"path":"https://canmod.github.io/macpan2/reference/mp_rbf.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fit a Time-Varying Parameter with Radial Basis Functions — mp_rbf","text":"tv String giving name parameter. dimension Number bases. initial_weights Optional vector dimensions elements. parameters fitted determine tv varies time. seed Optional random seed use generate initial_weights provided. prior_sd Prior standard deviation default value radial basis function coefficients, defaults 1. fit_prior_sd prior sd fitted. sparse_tol Tolerance radial basis function outputs set exactly zero. Small values accurate slower. Lack accuracy can visually apparent jumps graphs time-varying parameter.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reduce.html","id":null,"dir":"Reference","previous_headings":"","what":"Reduce Model — mp_reduce","title":"Reduce Model — mp_reduce","text":"Reduce model removing model structure (e.g. mp_per_capita_flow), expression lists plain R formulas.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reduce.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reduce Model — mp_reduce","text":"","code":"mp_reduce(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_reduce.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reduce Model — mp_reduce","text":"model model object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reference.html","id":null,"dir":"Reference","previous_headings":"","what":"Reference Index — mp_reference","title":"Reference Index — mp_reference","text":"Extract index used reference generating position vectors.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_reference.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reference Index — mp_reference","text":"","code":"mp_reference(x, dimension_name)"},{"path":"https://canmod.github.io/macpan2/reference/mp_reference.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reference Index — mp_reference","text":"x Object dimension_name Name dimension used ledger applicable.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rename.html","id":null,"dir":"Reference","previous_headings":"","what":"Rename Index Columns — mp_rename","title":"Rename Index Columns — mp_rename","text":"Rename Index Columns","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_rename.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Rename Index Columns — mp_rename","text":"","code":"mp_rename(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_rename.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Rename Index Columns — mp_rename","text":"x index columns renamed. ... Name-value pairs. name gives new name value character vector giving old name.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_sim_bounds.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulation Bounds (Experimental) — mp_sim_bounds","title":"Simulation Bounds (Experimental) — mp_sim_bounds","text":"Set simulation bounds (start time end time) calibration. used override default simulation bounds taken observed data passed mp_tmb_calibrator. first date first simulated time step (chosen first data point infectious individuals can built ) second date last simulated time step (chosen last data point can forecast period). last argument gives scale single time step (case always daily).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_sim_bounds.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulation Bounds (Experimental) — mp_sim_bounds","text":"","code":"mp_sim_bounds(sim_start, sim_end, time_scale)"},{"path":"https://canmod.github.io/macpan2/reference/mp_sim_bounds.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulation Bounds (Experimental) — mp_sim_bounds","text":"sim_start Start time simulation. sim_end End time simulation. time_scale Qualitative description size time step. currently \"steps\", \"daily\", \"weekly\" allowed, \"steps\" recommended version two poorly tested throw warning. recommended \"steps\" option assumes positive integers used indicate particular point simulation.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_simulator.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulator — mp_simulator","title":"Simulator — mp_simulator","text":"Construct simulator model specification object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_simulator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulator — mp_simulator","text":"","code":"mp_simulator(model, time_steps, outputs, default = list())"},{"path":"https://canmod.github.io/macpan2/reference/mp_simulator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulator — mp_simulator","text":"model model specification object. time_steps many time steps simulated simulations requested? outputs Character vector names model quantities outputted simulations requested. default Named list numerical objects update default values defined model specification object. number objects can updated .","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_slices.html","id":null,"dir":"Reference","previous_headings":"","what":"Slice an index — mp_slices","title":"Slice an index — mp_slices","text":"Slice index","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_slices.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Slice an index — mp_slices","text":"","code":"mp_slices(index, unpack = c(\"no\", \"maybe\", \"yes\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_slices.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Slice an index — mp_slices","text":"index Index slice . unpack Place factors global environment?","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_square.html","id":null,"dir":"Reference","previous_headings":"","what":"Self Cartesian Product — mp_square","title":"Self Cartesian Product — mp_square","text":"Self Cartesian Product","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_square.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Self Cartesian Product — mp_square","text":"","code":"mp_square(x, suffixes = c(\"A\", \"B\"))"},{"path":"https://canmod.github.io/macpan2/reference/mp_square.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Self Cartesian Product — mp_square","text":"x index. suffixes Length-2 character vector giving suffixes disambiguate column names output.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_state_dependence_frame.html","id":null,"dir":"Reference","previous_headings":"","what":"State Dependence Frame — mp_state_dependence_frame","title":"State Dependence Frame — mp_state_dependence_frame","text":"Data frame giving states per-capita flow rates directly depend . intended plotting diagrams mathematical analysis, describe indirect dependence flow rates state variables.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_dependence_frame.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"State Dependence Frame — mp_state_dependence_frame","text":"","code":"mp_state_dependence_frame(spec)"},{"path":"https://canmod.github.io/macpan2/reference/mp_state_dependence_frame.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"State Dependence Frame — mp_state_dependence_frame","text":"spec Model specification spec.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":null,"dir":"Reference","previous_headings":"","what":"State Variables — mp_state_vars","title":"State Variables — mp_state_vars","text":"Get state variables model specification.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"State Variables — mp_state_vars","text":"","code":"mp_state_vars(spec)"},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"State Variables — mp_state_vars","text":"spec Model specification (mp_tmb_model_spec).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_state_vars.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"State Variables — mp_state_vars","text":"Character vector names state variables explicitly represented model using functions like mp_per_capita_flow.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":null,"dir":"Reference","previous_headings":"","what":"Structured Vectors — mp_structured_vector","title":"Structured Vectors — mp_structured_vector","text":"documentation originally mp_index() cleaned See issue #131. Also experimental feature.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Structured Vectors — mp_structured_vector","text":"","code":"mp_structured_vector(x, ...)  mp_set_numbers(vector, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Structured Vectors — mp_structured_vector","text":"x index. ... Passed S3 methods. vector index.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Structured Vectors — mp_structured_vector","text":"mp_set_numbers(): Update numerical values structured vector. TODO: details syntax.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_structured_vector.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Structured Vectors — mp_structured_vector","text":"","code":"state = mp_index(   Epi = c(\"S\", \"I\", \"S\", \"I\"),   Age = c(\"young\", \"young\", \"old\", \"old\") ) state_vector = (state   |> mp_structured_vector()   |> mp_set_numbers(Epi = c(S = 1000))   |> mp_set_numbers(Epi = c(I = 1), Age = \"old\") ) print(state_vector) #> S.young I.young   S.old   I.old  #>    1000       0    1000       1"},{"path":"https://canmod.github.io/macpan2/reference/mp_subset.html","id":null,"dir":"Reference","previous_headings":"","what":"Subset of Indexes — mp_subset","title":"Subset of Indexes — mp_subset","text":"Take subset rows index table (see mp_index) produce another index table. mp_subset function gives rows match certain criterion mp_setdiff gives rows match.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_subset.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Subset of Indexes — mp_subset","text":"","code":"mp_subset(x, ...)  mp_setdiff(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_subset.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Subset of Indexes — mp_subset","text":"x Model index. ... Name-value pairs. names columns (sets columns using dot-concatenation) x values character vectors refer labels respect columns. values determine resulting subset.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_symmetric.html","id":null,"dir":"Reference","previous_headings":"","what":"Symmetric Self Cartesian Product — mp_symmetric","title":"Symmetric Self Cartesian Product — mp_symmetric","text":"Symmetric Self Cartesian Product","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_symmetric.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Symmetric Self Cartesian Product — mp_symmetric","text":"","code":"mp_symmetric(x, y_labelling_column_names, exclude_diag = TRUE)"},{"path":"https://canmod.github.io/macpan2/reference/mp_symmetric.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Symmetric Self Cartesian Product — mp_symmetric","text":"x index. y_labelling_column_names TODO exclude_diag 'diagonal' commponents excluded output.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_time_scale.html","id":null,"dir":"Reference","previous_headings":"","what":"Time Scale — mp_time_scale","title":"Time Scale — mp_time_scale","text":"Time Scale","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_time_scale.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Time Scale — mp_time_scale","text":"","code":"mp_time_scale(start, end, time_step_scale = c(\"steps\", \"daily\", \"weekly\"), ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_time_scale.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Time Scale — mp_time_scale","text":"start First date time first time step end Last date time last time step time_step_scale TODO ... TODO","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb.html","id":null,"dir":"Reference","previous_headings":"","what":"Get Underlying TMB Object — mp_tmb","title":"Get Underlying TMB Object — mp_tmb","text":"Get result TMB::MakeADFun underlying TMB-based model macpan2.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get Underlying TMB Object — mp_tmb","text":"","code":"mp_tmb(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get Underlying TMB Object — mp_tmb","text":"model object based TMB.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":null,"dir":"Reference","previous_headings":"","what":"Make TMB Calibrator — mp_tmb_calibrator","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"Construct object can get used calibrate object produced mp_tmb_model_spec mp_tmb_library, possibly modified mp_tmb_insert mp_tmb_update.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"","code":"mp_tmb_calibrator(   spec,   data,   traj,   par,   tv = character(),   outputs = traj,   default = list(),   time = NULL )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"spec TMB model spec fit data. specs can produced mp_tmb_model_spec mp_tmb_library, possibly modified mp_tmb_insert mp_tmb_update. data data frame containing trajectories fit possibly time-varying parameters. data must format produced mp_trajectory. traj character vector giving names trajectories fit data, named list likelihood distributions specified distribution trajectory. par character vector giving names parameters, either time-varying , fit using trajectory match. tv character vector giving names parameters make time-varying according values data, radial basis function specified mp_rbf. outputs character vector outputs generated mp_trajectory, mp_trajectory_sd, mp_trajectory_ensemble called optimized calibrator. default just trajectories listed traj. default list default values use update defaults spec. default nothing updated. Alternatively one use mp_tmb_update update spec outside function. Indeed approach necessary new expressions, addition default updates, need added spec (e.g. seasonally varying transmission). time Specify start end time simulated trajectories, time period associated time step. Currently valid choice NULL, takes simulation bounds data.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_calibrator.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Make TMB Calibrator — mp_tmb_calibrator","text":"","code":"spec = mp_tmb_library(\"starter_models\", \"sir\", package = \"macpan2\") sim = mp_simulator(spec, 50, \"infection\") data = mp_trajectory(sim) cal = mp_tmb_calibrator(     spec   , data   , traj = \"infection\"   , par = \"beta\"   , default = list(beta = 0.25) ) mp_optimize(cal) #> outer mgc:  389.7835  #> outer mgc:  259.2344  #> outer mgc:  40.03711  #> outer mgc:  1.594322  #> outer mgc:  0.002775624  #> outer mgc:  8.4447e-09  #> $par #> params  #>    0.2  #>  #> $objective #> [1] 49.74796 #>  #> $convergence #> [1] 0 #>  #> $iterations #> [1] 5 #>  #> $evaluations #> function gradient  #>        6        6  #>  #> $message #> [1] \"relative convergence (4)\" #>  mp_tmb_coef(cal)  ## requires broom.mixed package #> outer mgc:  8.4447e-09  #> outer mgc:  11.74622  #> outer mgc:  12.05664  #> outer mgc:  31.01941  #>     term  mat row col default  type estimate   std.error #> 1 params beta   0   0    0.25 fixed      0.2 0.009166433"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":null,"dir":"Reference","previous_headings":"","what":"TMB Model Coefficient Table — mp_tmb_coef","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"TMB Model Coefficient Table","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"","code":"mp_tmb_coef(model, back_transform = TRUE, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"model Object contains information model coefficients. back_transform boolean indicate model coefficients back transformed display defaults, estimates, confidence intervals original scale. Coefficient names also stripped transformation identifier. Currently, back transformation applies log transformed coefficients named \"log_\" prefix logit transformed coefficients named \"logit_\" prefix. Back transformation also applies time varying parameters distributional parameters get automatic prefixes used. back_transform defaults TRUE. ... Arguments pass onto broom.mixed::tidy.TMB method.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_coef.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"TMB Model Coefficient Table — mp_tmb_coef","text":"data frame describes fitted coefficients.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":null,"dir":"Reference","previous_headings":"","what":"Expression List — mp_tmb_expr_list","title":"Expression List — mp_tmb_expr_list","text":"Create list expressions defining compartmental model TMB.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Expression List — mp_tmb_expr_list","text":"","code":"mp_tmb_expr_list(   before = list(),   during = list(),   after = list(),   .simulate_exprs = character(0L) )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Expression List — mp_tmb_expr_list","text":"List formulas evaluated order provided simulation loop begins. formula must left hand side gives name matrix updated, right hand side giving expression containing names matrices model, functions defined macpan2.cpp, numerical literals (e.g. 3.14). available functions described engine_functions. Names can provided components , names unique.  names used .simulate_exprs argument. List formulas evaluated every iteration simulation loop, rules . List formulas evaluated simulation loop, rules . .simulate_exprs Character vector names expressions evaluated within TMB simulate blocks. useful expression evaluated computation objective function gradients (e.g. expression contains randomness discontinuities break automatic differentiation machinery TMB).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Expression List — mp_tmb_expr_list","text":"Object class ExprList following methods.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"Expression List — mp_tmb_expr_list","text":"$data_arg(...): Return following components data structure pass C++. expr_output_id – Indices list matrices identifying matrix produced. expr_sim_block – Identified whether expression evaluated inside simulate macro within TMB. expr_num_p_table_rows – Number rows associated expression parse table (p_table_*) eval_schedule – Vector giving number expressions evaluate phase (, , ) simulation. p_table_x – Parse table column giving index looking either function, matrix, literal. p_table_n – Parse table column giving number arguments functions. p_table_i – Parse table column giving indices looking rows parse table corresponding first argument function.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_expr_list.html","id":"method-arguments","dir":"Reference","previous_headings":"","what":"Method Arguments","title":"Expression List — mp_tmb_expr_list","text":"...: Character vector containing names matrices model.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":null,"dir":"Reference","previous_headings":"","what":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"Covariance Fixed Effect Estimates","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"","code":"mp_tmb_fixef_cov(model)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"model Object contains information fitted model parameters.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_fixef_cov.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Covariance of Fixed Effect Estimates — mp_tmb_fixef_cov","text":"covariance matrix.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":null,"dir":"Reference","previous_headings":"","what":"Modify a TMB Model Spec — mp_tmb_insert","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"Insert, update, delete elements TMB model spec, produced using mp_tmb_library mp_tmb_model_spec, mp_tmb_delete. difference mp_tmb_insert mp_tmb_update former shifts positions existing expressions make room new expressions, whereas latter overwrites existing expressions using new expressions. treatment new default values integers . examples clarify difference. Note mp_tmb_delete contain expressions argument, necessary specify new expressions case deletion.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"","code":"mp_tmb_insert(   model,   phase = \"during\",   at = 1L,   expressions = list(),   default = list(),   integers = list(),   must_save = character(),   must_not_save = character(),   sim_exprs = character() )  mp_tmb_update(   model,   phase = \"during\",   at = 1L,   expressions = list(),   default = list(),   integers = list(),   must_save = character(),   must_not_save = character(),   sim_exprs = character() )  mp_tmb_delete(   model,   phase,   at,   default = character(),   integers = character(),   must_save = character(),   must_not_save = character(),   sim_exprs = character() )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"model TMB model spec object produced using mp_tmb_library mp_tmb_model_spec. phase phase expressions inserted, updated, deleted. Expression number, can identified printing model, expressions inserted updated. inserted existing expressions number higher shifted new expressions added. updated, existing expressions number + length(expressions) - 1 replaced new expressions. mp_tmb_delete, numeric vector integers identifying expressions delete model. expressions Expressions insert model spec replace existing expressions. default Named list objects, can coerced numeric matrix. names refer variables appear , , . mp_tmb_delete, character vector objects delete model. integers Named list vectors can coerced integer vectors. integer vectors can used name model formulas provide indexing matrices grouping factors group_sums. mp_tmb_delete, character vector objects delete model. must_save Character vector names matrices must values stored every iteration simulation loop. example, matrix user want returned impacts dynamics time lag must saved therefore list. must_not_save Character vector names matrices must values stored every iteration simulation loop. example, user may ask return large matrix create performance issues stored iteration. creator model can mark matrices making impossible user model save full simulation history. sim_exprs Character vector names , , expressions must evaluated simulations produced objective function evaluated. example, expressions generate stochasticity listed sim_exprs TMB objective functions must continuous.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"new model spec object updated /inserted information.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"modifications update model specification -place. Instead output mp_tmb_insert, mp_tmb_update, mp_tmb_delete define new model specification saved want use new model (e.g., new_model = mp_tmb_insert(model, ...)).","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Modify a TMB Model Spec — mp_tmb_insert","text":"","code":"si = mp_tmb_library(\"starter_models\", \"si\", package = \"macpan2\") print(si) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       N         100.0 #>    beta           0.2 #>       I           1.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  #>      abs_rate = \"infection\") #>   ## Update the mixing process to include  ## optional phenomenological heterogeneity. ## We need mp_tmb_update here so that  ## the previous infection expression is ## overwritten. mp_tmb_update(si, phase = \"during\"   , at = 1   , expressions = list(infection ~ beta * I * (S/N)^zeta)   , default = list(zeta = 1) ) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       N         100.0 #>    beta           0.2 #>       I           1.0 #>    zeta           1.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: infection ~ beta * I * (S/N)^zeta #>   ## Parameterize with log_beta in place of beta. ## We need mp_tmb_insert here so that the ## existing expression for computing the initial ## number of susceptible indiviudals is not ## overwritten. mp_tmb_insert(si, phase = \"before\"   , at = 1   , expressions = list(beta ~ exp(log_beta))   , default = list(log_beta = log(0.5)) ) #> --------------------- #> Default values: #> --------------------- #>    matrix row col       value #>         N         100.0000000 #>      beta           0.2000000 #>         I           1.0000000 #>  log_beta          -0.6931472 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: beta ~ exp(log_beta) #> 2: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  #>      abs_rate = \"infection\") #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert_reports.html","id":null,"dir":"Reference","previous_headings":"","what":"Insert Reports — mp_tmb_insert_reports","title":"Insert Reports — mp_tmb_insert_reports","text":"version mp_tmb_insert making convenient transform incidence variable reports variable, accounts reporting delays -reporting. new reports variable convolution simulation history incidence variable kernel proportional Gamma distribution reporting delay times.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert_reports.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Insert Reports — mp_tmb_insert_reports","text":"","code":"mp_tmb_insert_reports(   model,   incidence_name,   report_prob,   mean_delay,   cv_delay,   reports_name = sprintf(\"reported_%s\", incidence_name),   report_prob_name = sprintf(\"%s_report_prob\", incidence_name),   mean_delay_name = sprintf(\"%s_mean_delay\", incidence_name),   cv_delay_name = sprintf(\"%s_cv_delay\", incidence_name) )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_insert_reports.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Insert Reports — mp_tmb_insert_reports","text":"model model produced mp_tmb_model_spec. incidence_name Name incidence variable transformed. report_prob Value use reporting probability; proportion cases get reported. mean_delay Mean Gamma distribution reporting delay times. cv_delay Coefficient variation Gamma distribution reporting delay times. reports_name Name new reports variable. report_prob_name Name variable containing report_prob. mean_delay_name Name variable containing mean_delay. cv_delay_name Name variable containing cv_delay.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":null,"dir":"Reference","previous_headings":"","what":"TMB Library — mp_tmb_library","title":"TMB Library — mp_tmb_library","text":"Get TMB model specification model library.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"TMB Library — mp_tmb_library","text":"","code":"mp_tmb_library(..., package = NULL, alternative_specs = FALSE)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"TMB Library — mp_tmb_library","text":"... File path components pointing directory contains R script creates object called spec, produced mp_tmb_model_spec. package NULL, file.path used put together ... components package name package (character string) system.file used put together ... components. alternative_specs TRUE, return list alternative specification objects. models without alternatives cause return value list one element containing spec object.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_library.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"TMB Library — mp_tmb_library","text":"","code":"mp_tmb_library(     \"starter_models\"   , \"si\"   , package = \"macpan2\" ) #> --------------------- #> Default values: #> --------------------- #>  matrix row col value #>       N         100.0 #>    beta           0.2 #>       I           1.0 #>  #> --------------------- #> Before the simulation loop (t = 0): #> --------------------- #> 1: S ~ N - 1 #>  #> --------------------- #> At every iteration of the simulation loop (t = 1 to T): #> --------------------- #> 1: mp_per_capita_flow(from = \"S\", to = \"I\", rate = \"beta * I / N\",  #>      abs_rate = \"infection\") #>"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_model_spec.html","id":null,"dir":"Reference","previous_headings":"","what":"Specify a TMB Model — mp_tmb_model_spec","title":"Specify a TMB Model — mp_tmb_model_spec","text":"Specify model TMB engine.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_model_spec.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Specify a TMB Model — mp_tmb_model_spec","text":"","code":"mp_tmb_model_spec(   before = list(),   during = list(),   after = list(),   default = list(),   integers = list(),   must_save = character(),   must_not_save = character(),   sim_exprs = character(),   state_update = c(\"euler\", \"rk4\", \"euler_multinomial\", \"hazard\") )"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmb_model_spec.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Specify a TMB Model — mp_tmb_model_spec","text":"List formulas evaluated (order provided) simulation loop begins. formula must left hand side gives name matrix updated, right hand side giving expression containing names matrices model, functions defined TMB engine, numerical literals (e.g. 3.14). available functions TMB engine  can described engine_functions. Names can provided components , names unique. names used sim_exprs argument. List formulas evaluated every iteration simulation loop, rules . List formulas evaluated simulation loop, rules . default Named list objects, can coerced numeric matrix. names refer variables appear , , . integers Named list vectors can coerced integer vectors. integer vectors can used name model formulas provide indexing matrices grouping factors group_sums. must_save Character vector names matrices must values stored every iteration simulation loop. example, matrix user want returned impacts dynamics time lag must saved therefore list. must_not_save Character vector names matrices must values stored every iteration simulation loop. example, user may ask return large matrix create performance issues stored iteration. creator model can mark matrices making impossible user model save full simulation history. sim_exprs Character vector names , , expressions must evaluated simulations produced objective function evaluated. example, expressions generate stochasticity listed sim_exprs TMB objective functions must continuous. state_update (experimental) Optional character vector update state variables relevant. Options include \"euler\", \"rk4\", \"euler_multinomial\".","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmbstan_coef.html","id":null,"dir":"Reference","previous_headings":"","what":"Model Coefficient Table with stan — mp_tmbstan_coef","title":"Model Coefficient Table with stan — mp_tmbstan_coef","text":"Leverages tmbstan broom.mixed packages generate MCMC-based coefficient tables.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_tmbstan_coef.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model Coefficient Table with stan — mp_tmbstan_coef","text":"","code":"mp_tmbstan_coef(model, tmbstan_args = list(), ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_tmbstan_coef.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model Coefficient Table with stan — mp_tmbstan_coef","text":"model Object contains information model coefficients. tmbstan_args Arguments pass tmbstan, used generate rstan object underlying TMB object. ... Arguments pass onto broom.mixed::tidy.stanfit method.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_traj.html","id":null,"dir":"Reference","previous_headings":"","what":"Trajectory Specification — mp_traj","title":"Trajectory Specification — mp_traj","text":"Specify set trajectories fit. output function intended passed traj argument mp_tmb_calibrator.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_traj.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Trajectory Specification — mp_traj","text":"","code":"mp_traj(likelihood = list(), condensation = list())"},{"path":"https://canmod.github.io/macpan2/reference/mp_traj.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Trajectory Specification — mp_traj","text":"likelihood List likelihood components. names list identify trajectory associated likelihood component. condensation List condensation methods. names list identify trajectories produced condensation method.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":null,"dir":"Reference","previous_headings":"","what":"Trajectory — mp_trajectory","title":"Trajectory — mp_trajectory","text":"Return simulations trajectory output variables dynamical model simulator. see functionality context, please see vignette(\"quickstart\").","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Trajectory — mp_trajectory","text":"","code":"mp_trajectory(model, include_initial = FALSE)  mp_trajectory_sd(model, conf.int = FALSE, conf.level = 0.95)  mp_trajectory_ensemble(model, n, probs = c(0.025, 0.975))  mp_trajectory_sim(model, n, probs = c(0.025, 0.25, 0.5, 0.75, 0.975))  mp_trajectory_replicate(model, n)"},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Trajectory — mp_trajectory","text":"model dynamical model simulator produced mp_simulator. include_initial initial values simulation included output? TRUE include outputs time == 0 associated initial values. See mp_initial another approach getting initial values. conf.int confidence intervals produced? conf.level conf.int TRUE, confidence level used?  example, default 0.95 corresponds 95% confidence intervals. n Number random trajectories simulate. probs Numeric vector probabilities corresponding quantiles summarizing results random realizations.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Trajectory — mp_trajectory","text":"data frame one row simulated value following columns. matrix Name variable model. variables matrix-valued macpan2 (scalars technically 1--1 matrices), explains name field. hindsight called variable. time Time index simulated value, time = 0 indicating initial values. row 0-based index row matrix, name row matrix row names (names column vectors) supplied default value matrix. col 0-based index column matrix, name column matrix column names supplied default value matrix. also possible column blank everything either scalar column vector (common case). value (mp_trajectory mp_trajectory_sd) Simulation values. sd (mp_trajectory_sd ) standard deviations simulated values accounting parameter estimation uncertainty. conf.low (mp_trajectory_sd ) lower bounds confidence interval simulated values. conf.high (mp_trajectory_sd ) upper bounds confidence interval simulated values. n% (mp_trajectory_[ensemble|sim]) n-th quantiles simulation values repeated simulations.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Trajectory — mp_trajectory","text":"mp_trajectory_sd(): Simulate trajectory includes uncertainty information provided sdreport function TMB default settings. mp_trajectory_ensemble(): Simulate trajectory includes uncertainty information provided repeatedly sampling normal approximation distribution fitted parameters, generating one trajectory samples. quantiles empirical distribution trajectories can used produce confidence interval fitted trajectory. mp_trajectory_sim(): Generate quantiles n realizations trajectory. Instead value column output data frame, one column quantiles defined probs. mp_trajectory_replicate(): Generate list n simulation results.","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_trajectory.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Trajectory — mp_trajectory","text":"","code":"spec = mp_tmb_library(\"starter_models\"   , \"si\"   , package = \"macpan2\" ) simulator = mp_simulator(spec   , time_steps = 10L   , outputs = c(\"infection\", \"I\") ) trajectory = mp_trajectory(simulator) print(trajectory) #>       matrix time row col     value #> 1          I    1   0   0 1.1980000 #> 2  infection    1   0   0 0.1980000 #> 3          I    2   0   0 1.4347296 #> 4  infection    2   0   0 0.2367296 #> 5          I    3   0   0 1.7175586 #> 6  infection    3   0   0 0.2828290 #> 7          I    4   0   0 2.0551703 #> 8  infection    4   0   0 0.3376117 #> 9          I    5   0   0 2.4577569 #> 10 infection    5   0   0 0.4025866 #> 11         I    6   0   0 2.9372272 #> 12 infection    6   0   0 0.4794702 #> 13         I    7   0   0 3.5074180 #> 14 infection    7   0   0 0.5701908 #> 15         I    8   0   0 4.1842977 #> 16 infection    8   0   0 0.6768796 #> 17         I    9   0   0 4.9861405 #> 18 infection    9   0   0 0.8018428 #> 19         I   10   0   0 5.9336454 #> 20 infection   10   0   0 0.9475049"},{"path":"https://canmod.github.io/macpan2/reference/mp_triangle.html","id":null,"dir":"Reference","previous_headings":"","what":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","title":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","text":"Self Cartesian Product Excluding One -Diagonal Side","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_triangle.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","text":"","code":"mp_triangle(   x,   y_labelling_column_names,   exclude_diag = TRUE,   lower_tri = FALSE )"},{"path":"https://canmod.github.io/macpan2/reference/mp_triangle.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Self Cartesian Product Excluding One Off-Diagonal Side — mp_triangle","text":"x index. y_labelling_column_names TODO exclude_diag 'diagonal' commponents excluded output. lower_tri lower triangular components include output. FALSE result upper triangular.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_union.html","id":null,"dir":"Reference","previous_headings":"","what":"Union of Indexes — mp_union","title":"Union of Indexes — mp_union","text":"Union Indexes","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_union.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Union of Indexes — mp_union","text":"","code":"mp_union(...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_union.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Union of Indexes — mp_union","text":"... Indexes.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/mp_zero_vector.html","id":null,"dir":"Reference","previous_headings":"","what":"Zero Vector — mp_zero_vector","title":"Zero Vector — mp_zero_vector","text":"Create numeric vector zeros names given x","code":""},{"path":"https://canmod.github.io/macpan2/reference/mp_zero_vector.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Zero Vector — mp_zero_vector","text":"","code":"mp_zero_vector(x, ...)"},{"path":"https://canmod.github.io/macpan2/reference/mp_zero_vector.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Zero Vector — mp_zero_vector","text":"x Object representing names output vector. commonly character vector. ... Passed S3 methods.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Names and Labels — names_and_labels","title":"Names and Labels — names_and_labels","text":"page describes functions giving names labels entities structured models.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names and Labels — names_and_labels","text":"","code":"to_labels(x)  to_names(x)  to_name(x)  to_name_pairs(x)  to_values(x)"},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names and Labels — names_and_labels","text":"x Object extract name, names, labels, name-pairs, values. types objects work functions.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Names and Labels — names_and_labels","text":"Character vector (numeric vector case to_values) describes x.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Names and Labels — names_and_labels","text":"to_labels(): Extract vector describing rows data frame values numeric vector. to_names(): Extract character vector describing character-valued columns data frame flattened structure numeric vector. Names obey following restrictions:  (1) dots, (2) values must start letter, (3) characters must letters, numbers, underscore. to_name(): Extract string (.e. length-1 character vector) describing character-valued columns data frame flattened structure numeric vector. name object dot-concatenation names. to_name_pairs(): character vector possible pairwise dot-concatenations set names. to_values(): Extract numeric column data frame single numerical column. data frame might one column, one can numeric. function also turn numeric matrix array objects dimnames flattened numeric vector labels produced appropriately dot-concatenating dimnames.","code":""},{"path":"https://canmod.github.io/macpan2/reference/names_and_labels.html","id":"context","dir":"Reference","previous_headings":"","what":"Context","title":"Names and Labels — names_and_labels","text":"goal macpan2 provide mechanism representing structured compartmental models. example model compartment SEIR model split set spatial locations set age groups. crucial difficult assign meaningful consistent names compartments, flow rates, transmission rates, contact rates, sub-population sizes, parameters determining quantities. names convey different quantities relate one another. example, names make clear rate flow two compartments specific , say, age group location compartments. naming system facilitate identifying model quantities sets quantities. example, spatially structured model might want refer states particular location (e.g. Toronto) specific state within location (e.g. susceptible individuals Toronto). Model entities (e.g. states, flow rates, transmission rates), can described using data frame string-valued columns. rows data frames represent entities represented.  columns data frame represent different ways describe rows.   Non-empty values cell must contain letters, numbers, underscores, must start letter. Empty values zero-length strings can used indicate partitions applicable variables. purpose restrictions facilitate construction strings character vectors summarize different aspects data frame. taken together, summaries can inverted restore full labelled partition represent zero information loss. equivalence allows us go back--forth two representations without loosing information, perhaps gaining convenience. three types summaries: names, name, labels. names data frame names string-valued columns.   name data frame dot-concatenation names.   labels data frame row-wise dot-concatenation string-valued columns.   labels give unique single character string referring variable. labels one either names name, one may recover labelled partition. labels provide convenient names variables – .e. rownames. convention use UpperCamelCase partition names modified form snake_case variable labels. modification snake case allows single uppercase letters order accommodate convention epidemiology using single uppercase letters refer state variables. example, S, , R, well I_mild I_severe, consistent modified snake case style.","code":"EpiSympVax = data.frame(   Epi = c(rep(c(\"S\", \"E\", \"I\", \"I\", \"R\", \"beta\"), 2), \"alpha\", \"gamma\", \"gamma\", \"infectiousness\", \"infectiousness\", \"\"),   Symp = c(rep(c(\"\", \"\", \"mild\", \"severe\", \"\", \"\"), 2), \"\", \"mild\", \"severe\", \"mild\", \"severe\", \"\"),   Vax = c(rep(c(\"unvax\", \"vax\"), each = 6), \"\", \"\", \"\", \"\", \"\", \"dose_rate\") ) EpiSympVax #>               Epi   Symp       Vax #> 1               S            unvax #> 2               E            unvax #> 3               I   mild     unvax #> 4               I severe     unvax #> 5               R            unvax #> 6            beta            unvax #> 7               S              vax #> 8               E              vax #> 9               I   mild       vax #> 10              I severe       vax #> 11              R              vax #> 12           beta              vax #> 13          alpha #> 14          gamma   mild #> 15          gamma severe #> 16 infectiousness   mild #> 17 infectiousness severe #> 18                       dose_rate to_names(EpiSympVax) #> [1] \"Epi\"  \"Symp\" \"Vax\" to_name(EpiSympVax) #> [1] \"Epi.Symp.Vax\" to_labels(EpiSympVax) #>  [1] \"S..unvax\"               \"E..unvax\"               \"I.mild.unvax\" #>  [4] \"I.severe.unvax\"         \"R..unvax\"               \"beta..unvax\" #>  [7] \"S..vax\"                 \"E..vax\"                 \"I.mild.vax\" #> [10] \"I.severe.vax\"           \"R..vax\"                 \"beta..vax\" #> [13] \"alpha..\"                \"gamma.mild.\"            \"gamma.severe.\" #> [16] \"infectiousness.mild.\"   \"infectiousness.severe.\" \"..dose_rate\""},{"path":"https://canmod.github.io/macpan2/reference/nlist.html","id":null,"dir":"Reference","previous_headings":"","what":"Self Naming List — nlist","title":"Self Naming List — nlist","text":"Self Naming List","code":""},{"path":"https://canmod.github.io/macpan2/reference/nlist.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Self Naming List — nlist","text":"","code":"nlist(...)"},{"path":"https://canmod.github.io/macpan2/reference/nlist.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Self Naming List — nlist","text":"... Objects put list","code":""},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":null,"dir":"Reference","previous_headings":"","what":"Radial Basis Functions — rbf","title":"Radial Basis Functions — rbf","text":"Compute set radial basis functions (dimension ).","code":""},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Radial Basis Functions — rbf","text":"","code":"rbf(time_steps, dimension, scale = time_steps/dimension)"},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Radial Basis Functions — rbf","text":"time_steps number time steps model dimension number gaussians basis scale width gaussians","code":""},{"path":"https://canmod.github.io/macpan2/reference/rbf.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Radial Basis Functions — rbf","text":"","code":"matplot(rbf(100, 5), type = \"l\")"},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":null,"dir":"Reference","previous_headings":"","what":"Print a table of contents of available models — show_models","title":"Print a table of contents of available models — show_models","text":"Collects information headers README files model directories returns results data frame","code":""},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Print a table of contents of available models — show_models","text":"","code":"show_models(   dir = system.file(\"starter_models\", package = \"macpan2\"),   show_missing = FALSE,   for_markdown = FALSE )"},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Print a table of contents of available models — show_models","text":"dir directory list show_missing (logical) include entries models README information? for_markdown (logical) format rendering table markdown-formatted links model readme files?","code":""},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Print a table of contents of available models — show_models","text":"data frame containing entries Directory (model directory), Title (model title), Description (short description)","code":""},{"path":"https://canmod.github.io/macpan2/reference/show_models.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Print a table of contents of available models — show_models","text":"","code":"show_models(show_missing = TRUE) #>                       Directory                    Title #> 1                     awareness         Awareness Models #> 2                           hiv                      HIV #> 3    lotka_volterra_competition           Lotka-Volterra #> 4  lotka_volterra_predator_prey           Lotka-Volterra #> 5                   macpan_base              Macpan Base #> 6                          nfds  NFDS and Vaccine Design #> 7                          seir               Basic SEIR #> 8                        shiver    SHIVER = SEIR + H + V #> 9                            si                 Basic SI #> 10                          sir                Basic SIR #> 11                    sir_demog      SIR with Demography #> 12                 sir_mosquito     Mosquito-Vector  SIR #> 13                   sir_waning SIR with Waning Immunity #> 14                           ww         Wastewater Model #>                                                                                                        Description #> 1                                                                     Behaviour modifications in response to death #> 2                                                                                               A simple HIV model #> 3                                                                             Simple two-species competition model #> 4                                                                                       Simple predator-prey model #> 5                                                         Re-implementation of the McMaster group's COVID-19 model #> 6  An ecological model using population genomics to design optimal vaccines as implemented in Colijn et al. (2020) #> 7                                                                      Simple epidemic model with an exposed class #> 8                                                       A modified SEIR model with Hospitalization and Vaccination #> 9                                                                                     A very simple epidemic model #> 10                                                                                    A very simple epidemic model #> 11                                                                               An SIR model with birth and death #> 12                                                                                  SIR model for mosquito vectors #> 13                                                                  A basic SIR model with a flow from R back to S #> 14                                                             Macpan base with an additional wastewater component"},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":null,"dir":"Reference","previous_headings":"","what":"Simple Iterated Simulation — simple_sims","title":"Simple Iterated Simulation — simple_sims","text":"Simple Iterated Simulation","code":""},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simple Iterated Simulation — simple_sims","text":"","code":"simple_sims(iteration_exprs, time_steps, int_vecs = list(), mats = list())"},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simple Iterated Simulation — simple_sims","text":"iteration_exprs List expressions pass engine. expressions allowed use valid engine_functions. expression evaluated order, iteration. number iterations controlled time_steps argument. time_steps Number time steps iterate. int_vecs Named list integer vectors. mats Named list matrices.","code":""},{"path":"https://canmod.github.io/macpan2/reference/simple_sims.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Simple Iterated Simulation — simple_sims","text":"data frame simulation results.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_positions.html","id":null,"dir":"Reference","previous_headings":"","what":"To Positions — to_positions","title":"To Positions — to_positions","text":"Return position vector indices corresponding input object.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_positions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"To Positions — to_positions","text":"","code":"to_positions(x)"},{"path":"https://canmod.github.io/macpan2/reference/to_positions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"To Positions — to_positions","text":"x object class can converted position vector.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":null,"dir":"Reference","previous_headings":"","what":"To String — to_string","title":"To String — to_string","text":"Convert object string.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"To String — to_string","text":"","code":"to_string(x)"},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"To String — to_string","text":"x Object convert string.","code":""},{"path":"https://canmod.github.io/macpan2/reference/to_string.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"To String — to_string","text":"length-1 character vector.","code":""},{"path":"https://canmod.github.io/macpan2/reference/transform_distr_param.html","id":null,"dir":"Reference","previous_headings":"","what":"Distributional Parameter Transformation — transform_distr_param","title":"Distributional Parameter Transformation — transform_distr_param","text":"Objects used mp_identity - Identity transformation mp_log - Log transformation mp_logit - Logit transformation mp_sqrt - Square-root transformation","code":""},{"path":"https://canmod.github.io/macpan2/reference/transform_distr_param.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Distributional Parameter Transformation — transform_distr_param","text":"","code":"mp_identity  mp_log  mp_logit  mp_sqrt"},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-5-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.5.0 (news for this version is in-progress)","text":"Delete elements model specifications mp_tmb_delete.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-4-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.4.0 (news for this version is in-progress)","text":"Repeated calls optimizer now start previous best parameter vector longer fit full covariance matrix sdreports","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"bug-fixes-1-4-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"macpan2 1.4.0 (news for this version is in-progress)","text":"Row vectors names longer break spec print methods","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-3-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.3.0","text":"longer exporting nlist. Removing -place modifications model specification objects mp_tmb_insert mp_tmb_update.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-3-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.3.0","text":"Define explicit state variable updates, choice applying mp_euler, mp_rk4, mp_euler_multinomial update methods, latter generating process error. New stochasticity engine functions rbinom reulermultinom. mp_tmb_fixef_cov function getting covariance matrix fixed effects. mp_trajectory_ensemble mp_trajectory_sim functions summarizing random variation trajectories. Unpacking assignment engine. means can things like c(x, y) ~ z, values z assigned elements x, y, etc… row-major order. to_name_pairs function returning pairwise dot-concatenations elements character vector without dots. to_values function extracting column data frame single numerical column turning numeric matrices arrays dimnames flattened numeric vector labels produced appropriately dot-concatenating dimnames.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"bug-fixes-1-3-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"macpan2 1.3.0","text":"Several bugs related input handling mp_tmb_calibrator (#176)","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"doc-fixes-and-updates-1-3-0","dir":"Changelog","previous_headings":"","what":"Doc Fixes and Updates","title":"macpan2 1.3.0","text":"New installation instructions installing r-universe. New vignette: real_data. Document to_name, to_names, to_labels, handle naming structured objects. Document print function ?engine_functions. simple_sims example ?engine_functions now runs without error. Help file examples mp_tmb_insert mp_tmb_update. Readme/vignette examples better expose calls library user.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-1-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.1.0","text":"simple_sims longer returns outputs zeroth time-step. Using last.par.best finalize TMB objective function following optimization. group_sums now checks bad group indexes. rbind_lag now throws error lag > 1 conceptual errors case. get back can allow important cases adding argument initial conditions associated negative time steps.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-1-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.1.0","text":"Streamlined installation via r-universe. mp_tmb_calibrator mp_tmb_optimize functions calibration using simple restrictive trajectory matching model. Future releases allow functionality. mp_tmb_coef mp_tmbstan_coef tables statistical parameters used calibration. mp_trajectory_sd mp_trajectory_ensemble getting information fitted trajectory uncertainty. mp_tmb_update|insert functions creating new model specs existing ones. Parameters specified data frame can now place default values columns following names: \"default\", \"Default\", \"value\", \"Value\", \"val\", \"Val\" mp_tmb_library can return list model specs alternative_specs, model makes alternatives available. time_var engine function better old time_group, required two expressions rather one thing. time_group remain softly deprecated. Fixed effects extractor formatter. mp_default function extracting spec simulator defaults long-format. rbind_time allows integer vectors subsetting times options(macpan2_verbose = FALSE) turn flood information provided TMB. Note takes effect set creating TMB simulator.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"bug-fixes-1-1-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"macpan2 1.1.0","text":"Segfaults --range assignment.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"doc-fixes-and-updates-1-1-0","dir":"Changelog","previous_headings":"","what":"Doc Fixes and Updates","title":"macpan2 1.1.0","text":"(progress) Calibration vignette updated simpler quick-start, previous advanced material moved advanced vignette. mp_tmb_model_spec documentation filled . group_sums TMB engine function third argument updated old pre-1.0.0 behaviour.","code":""},{"path":[]},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"breaking-changes-1-0-0","dir":"Changelog","previous_headings":"","what":"Breaking Changes","title":"macpan2 1.0.0","text":"flows.csv, derivations.json files library, instead tmb.R files. Compartmental function, instead mp_tmb_model_spec mp_tmb_library. {group|row|col}Sums now called {group|row|col}_sums. Final argument group_sums used length output vector, now vector desired output length. TMBModel associated classes (ExprList) longer exported, favour mp_... functions similar things. Sort simulation output time step.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"new-features-1-0-0","dir":"Changelog","previous_headings":"","what":"New Features","title":"macpan2 1.0.0","text":"Constant integer vectors can now passed C++. Integer vectors can used subset assignment matrices (.e. integer subsetting left-hand-side). mp_trajectory() function, roughly equivalent model$report(..., .phases = \"\"). New print function TMB engine. need declare empty matrices creating TMB model objects, matrices derived automatically detected.","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"experimental-features-1-0-0","dir":"Changelog","previous_headings":"","what":"Experimental Features","title":"macpan2 1.0.0","text":"Model structure grammar (mp_index(), mp_join(), etc.) Log files","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"macpan2-003","dir":"Changelog","previous_headings":"","what":"macpan2 0.0.3","title":"macpan2 0.0.3","text":"Optimize C++ simulation history storage avoiding unnecessary allocations Use state flow names expression inserters Chattier validity checking Radial basis functions macpan-base – re-implementation McMaster group’s COVID-19 model macpan2 ww – wastewater model (doesn’t yet readme) new readme clean previous models Report expression broke C++ side Developer tools switching different C++ files working directories Package reference organization cleanup (thanks @bbolker ) Time-varying parameters vignette","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"macpan2-002","dir":"Changelog","previous_headings":"","what":"macpan2 0.0.2","title":"macpan2 0.0.2","text":"Interface optimization TMB simulation objects TMB simulation model updating caching Parameter transformations Get initial values matrices TMB simulation objects State flow variable names can used expressions contexts Example model indexing (thank @bbolker!) Engine function rbind_time defaults row binding full simulation history Fix bug entire model inflows outflows Fix bugs symbolic R-side manipulation expressions Fix previously broken argument_dots option model definition files (thank @Flynn-Primrose )","code":""},{"path":"https://canmod.github.io/macpan2/news/index.html","id":"macpan2-001","dir":"Changelog","previous_headings":"","what":"macpan2 0.0.1","title":"macpan2 0.0.1","text":"Initial release.","code":""}]