Merge main into GH-300/statistics-unit-tests-docs

documentation/assets/digitized_run_count.csv

@@ -0,0 +1,149 @@
+Bar0, 45.13896266557068
+Bar1, 38.08296460117502
+Bar2, 47.056746754867945
+Bar3, 9.96752615996775
+Bar4, 8.954357207131446
+Bar5, 13.94783276039606
+Bar6, 9.96752615996775
+Bar7, 23.102537941381186
+Bar8, 22.05318438308644
+Bar9, 30.122351400318404
+Bar10, 18.000508571741264
+Bar11, 14.852447896857047
+Bar12, 18.977492919119104
+Bar13, 4.03325086478371
+Bar14, 6.204327192290073
+Bar15, 5.299712055829087
+Bar16, 7.253680750584808
+Bar17, 4.503650735743423
+Bar18, 5.69774271587192
+Bar19, 11.993864065640341
+Bar20, 2.911528095572095
+Bar21, 14.780078685940165
+Bar22, 9.026726418048325
+Bar23, 4.503650735743423
+Bar24, 3.8885124429499607
+Bar25, 1.8621745372773595
+Bar26, 40.97773303785016
+Bar27, 20.895277008416397
+Bar28, 8.990541812589885
+Bar29, 4.7207583684940655
+Bar30, 10.003710765426192
+Bar31, 8.954357207131446
+Bar32, 2.8391588846552263
+Bar33, 15.467586189650508
+Bar34, 10.980695112804046
+Bar35, 29.00062863110678
+Bar36, 24.984137425220013
+Bar37, 8.918172601673005
+Bar38, 28.132198100104233
+Bar39, 21.98081517216956
+Bar40, 31.135520353154686
+Bar41, 15.97417066606865
+Bar42, 3.9608816538668417
+Bar43, 16.40838593156993
+Bar44, 5.878665743164109
+Bar45, 3.8885124429499607
+Bar46, 37.105980253797156
+Bar47, 10.944510507345605
+Bar48, 2.8391588846552263
+Bar49, 5.98721955953943
+Bar50, 2.7667896737383444
+Bar51, 3.8885124429499607
+Bar52, 43.07644015443965
+Bar53, 0.9213747953579461
+Bar54, 0.9575594008163741
+Bar55, 1.029928611733255
+Bar56, 12.898479202101328
+Bar57, 5.914850348622549
+Bar58, 1.7536207209020382
+Bar59, 5.010235212161577
+Bar60, 1.9345437481942405
+Bar61, 14.02020197131294
+Bar62, 15.105740135066117
+Bar63, 1.8983591427358002
+Bar64, 2.8029742791967855
+Bar65, 12.970848413018208
+Bar66, 7.90500364883671
+Bar67, 31.135520353154686
+Bar68, 16.082724482443968
+Bar69, 7.868819043378269
+Bar70, 26.90192151451731
+Bar71, 3.8885124429499607
+Bar72, 5.98721955953943
+Bar73, 3.9608816538668417
+Bar74, 0.016759658896960586
+Bar75, 0.8851901898995057
+Bar76, 7.868819043378269
+Bar77, 3.924697048408401
+Bar78, 3.8523278374915204
+Bar79, 7.977372859753591
+Bar80, 6.747096274166654
+Bar81, 12.862294596642885
+Bar82, 21.98081517216956
+Bar83, 25.5992757180135
+Bar84, 17.095893435280278
+Bar85, 14.997186318690794
+Bar86, 4.9378660012446955
+Bar87, 37.06979564833872
+Bar88, 30.01379758394308
+Bar89, 4.829312184869375
+Bar90, 12.102417882015661
+Bar91, 1.8983591427358002
+Bar92, 2.8391588846552263
+Bar93, 6.385250219582263
+Bar94, 2.7667896737383444
+Bar95, 8.881987996214576
+Bar96, 4.03325086478371
+Bar97, 11.993864065640341
+Bar98, 22.089368988544884
+Bar99, 2.947712701030535
+Bar100, 0.8851901898995057
+Bar101, 1.9707283536526807
+Bar102, 2.911528095572095
+Bar103, 0.8851901898995057
+Bar104, 1.9707283536526807
+Bar105, 0.9937440062748146
+Bar106, 4.7207583684940655
+Bar107, 0.9937440062748146
+Bar108, 0.05294426435540099
+Bar109, 0.8851901898995057
+Bar110, 10.003710765426192
+Bar111, 10.908325901887165
+Bar112, 31.063151142237807
+Bar113, 49.08308466054056
+Bar114, 1.8259899318189192
+Bar115, 3.8885124429499607
+Bar116, 8.954357207131446
+Bar117, 1.9345437481942405
+Bar118, 0.8851901898995057
+Bar119, 2.006912959111121
+Bar120, 0.8490055844410651
+Bar121, 5.010235212161577
+Bar122, 10.944510507345605
+Bar123, 14.092571182229822
+Bar124, 0.9575594008163741
+Bar125, 1.029928611733255
+Bar126, 1.029928611733255
+Bar127, 4.03325086478371
+Bar128, 1.9345437481942405
+Bar129, 4.03325086478371
+Bar130, 1.9707283536526807
+Bar131, 7.941188254295151
+Bar132, 5.154973633995326
+Bar133, 22.089368988544884
+Bar134, 16.04653987698553
+Bar135, 22.12555359400332
+Bar136, 12.03004867109878
+Bar137, 0.9213747953579461
+Bar138, 3.924697048408401
+Bar139, 1.8621745372773595
+Bar140, 1.8983591427358002
+Bar141, 5.878665743164109
+Bar142, 3.9608816538668417
+Bar143, 8.049742070670472
+Bar144, 5.0826044230784575
+Bar145, 5.227342844912206
+Bar146, 5.263527450370646
+Bar147, 5.299712055829087
+Bar148, 2.8753434901136536

documentation/assets/inference_algorithm.tex

@@ -0,0 +1,62 @@
+\documentclass[6pt,a4]{article}
+\usepackage[margin=0.5in]{geometry}
+
+% amsmath and amssymb packages, useful for mathematical formulas and symbols
+\usepackage{amsmath,amssymb}
+
+\usepackage{algorithm}
+\usepackage{algpseudocode}
+
+
+\begin{document}
+
+%\section{Inference Algorithm}
+\begin{algorithm}
+\caption{FlepiMoP Inference}\label{flepi-inference}
+\begin{algorithmic}[1]
+\State \textbf{Inputs:} initial parameter distribution $\mathcal{I}(\cdot)$, proposal distribution $g(\Theta)$, prior distribution $p(\Theta)$, \texttt{gempyor} epidemic model $Z(\Theta)$, likelihood function, ground-truth data $\mathcal{L}(D|Z(\Theta))$ , \textit{chimeric-reset} frequency $k_f$ (default: $k_f=\infty$) and \textit{chimeric-force} flag (default: False).
+\For{$m=1  \dots M$} \Comment{$M$: number of parallel MCMC chains}
+%  \Procedure{Initialize Chain}{$a,b$}    
+    \State $\Theta_{m,0} \sim \mathcal{I}(\cdot)$ \Comment{Sample initial set of parameters from config distribution}
+    \State  $\Theta^G_{m,0} \gets \Theta_{m,0}$ \Comment{Initialize global parameter chain}
+    \State $\Theta^G_{m,0} \gets \Theta_{m,0}$ \Comment{Initialize chimeric parameter chain}
+    \State $Z_{\Theta_{m,0}} \gets Z(\Theta_{m,0})$ \Comment{Compute the epidemic trajectory with \texttt{gempyor}}
+    %\State $\mathcal{L}(D^i|M^i)$  \textbf{for} $i=1  \dots N$ \Comment{Compute the initial likelihood for each node}
+    %\State Compute the overall initial likelihood, $\mathcal{L}(D|M))$
+  %\EndProcedure
+%s\item[]
+  \For{$k=1  \dots K$} \Comment{$K$: length of the MCMC chain}
+    \State  $\Theta^* \sim g(\Theta^*|\Theta^C_{m,k-1})$ \Comment{Generate a proposed set of parameters from chimeric chain}
+    \State $Z_{\Theta^*} \gets Z(\Theta^*)$ \Comment{Compute the epidemic trajectory with \texttt{gempyor}}
+    %\State Calculate the likelihood of the data given the proposed parameters for each subpopulation, $\mathcal{L}^i(D^i|Z^i(\Theta^*))$
+    %\State Calculate the overall likelihood with the proposed parameters, $\mathcal{L}(D|Z(\Theta^*))$
+      %\State Generate a uniform random number $u^G \sim \mathcal{U}[0,1]$
+      \State $\alpha^G \gets\min \left(1, \frac{\mathcal{L}(D|Z_{\Theta^*}) p(\Theta^*) g(\Theta_{m,k-1}|\Theta^*)}{\mathcal{L}(D|Z_{\Theta_{m,k-1}}) p(\Theta_{m,k-1}) g(\Theta^*|\Theta_{m,k-1})} \right)$ \Comment{Compute the global acceptance ratio from the likelihoods}
+      \State$ u \sim \mathcal{U}[0,1]$
+      \If{$\alpha^G > u$} \Comment{\emph{Accept} proposal to the global and chimeric parameter chains}
+        \State $\Theta^G_{m,k} \gets \Theta^*$
+        \State $\Theta_{m,k}^C \gets \Theta^*$
+      \EndIf
+      \If{$\alpha^G > u$ (or if \textit{chimeric-force}=True)} \Comment{Compute chimeric (local) acceptances on global rejection}% \Comment{on \emph{Reject} the proposal for the global chain or we }
+        \State $\Theta^G_{m,k} \gets \Theta^G_{m,k-1}$
+          \For{$i=1  \dots N$} \Comment{$N$: number of spatial nodes}
+            %\State Generate a uniform random number $u^i^C \sim \mathcal{U}[0,1]$
+            \State $\alpha_i^C \gets \frac{\mathcal{L}_i(D^i|Z^i_{\Theta^*}) p(\Theta^*) g(\Theta_{m,k-1}|\Theta^*)}{\mathcal{L}_i(D^i|Z^i_{\Theta_{m,k-1}}) p(\Theta_{m,k-1}) g(\Theta^*|\Theta_{m,k-1})}$ \Comment{Compute the \textit{chimeric} acceptance ratio in node $i$}
+            \If{$\alpha_i^C > u \sim  \mathcal{U}[0,1]$} \Comment{\emph{Accept} proposal to the chimeric parameter chain for this location}
+              \State $\Theta_{m,k,i}^C \gets \Theta^*_{i}$ 
+            \Else \Comment{\emph{Reject} proposal for the chimeric parameter chain for this location}
+              \State $\Theta_{m,k,i}^C \gets \Theta_{m,k-1,i}$ 
+            \EndIf
+            \If{$k \mod{k_f} =0$}
+                    \State $\Theta_{m,k}^C \gets \Theta^G_{m,k}$  \Comment{Optional: periodically reset chimeric chain}
+
+            \EndIf
+          \EndFor
+      \EndIf
+  \EndFor 
+\EndFor
+\State \textbf{return} the final global parameter values for each parallel chain $\theta_m = \{\Theta^G_{m,K}\}_m$
+\end{algorithmic}
+\end{algorithm}
+
+\end{document}

documentation/gitbook/README.md

@@ -27,15 +27,15 @@ The mathematical model within the pipeline is a _compartmental epidemic model_ e
 
 The structure of the desired model, as well as the parameter values and initial conditions, can be specified flexibly by the user in a no-code fashion. The pipeline allows for parameter values to change over time at discrete intervals, which can be used to specify time-dependent aspects of disease transmission and control (such as seasonality or vaccination campaigns).
 
-The model is embedded within a meta-population structure, which consists of a series of distinct subpopulations (e.g. states, provinces, or other communities) in which the model structure is repeated, albeit with potentially different parameter values. The subpopulations can interact, either through the movement of individuals or the influence of individuals in one subpopulation on the transition rate of individuals in another. 
+The model is embedded within a meta-population structure, which consists of a series of distinct subpopulations (e.g. states, provinces, or other communities) in which the model structure is repeated, albeit with potentially different parameter values. The subpopulations can interact, either through the movement of individuals or the influence of individuals in one subpopulation on the transition rate of individuals in another ;
 
-Within each subpopulation, the population is assumed to be well-mixed, meaning that interactions are assumed to be equally likely between any pair of individuals (since unique identities of individuals are not explicitly tracked). The same model structure can be simulated in a continuous-time deterministic or discrete-time stochastic manner. 
+Within each subpopulation, the population is assumed to be well-mixed, meaning that interactions are assumed to be equally likely between any pair of individuals (since unique identities of individuals are not explicitly tracked). The same model structure can be simulated in a continuous-time deterministic or discrete-time stochastic manner ;
 
-In addition to the variables described by the compartmental model, the model can track other observable variables (“outcomes”) that are functions of the basic model variables but do not themselves influence the dynamics (i.e., some portion of infections are reported as cases, depending on a testing rate). The model can be run iteratively to tune the values of certain parameters so that these outcome variables best match timeseries data provided by the user for a certain time period. 
+In addition to the variables described by the compartmental model, the model can track other observable variables (“outcomes”) that are functions of the basic model variables but do not themselves influence the dynamics (i.e., some portion of infections are reported as cases, depending on a testing rate). The model can be run iteratively to tune the values of certain parameters so that these outcome variables best match timeseries data provided by the user for a certain time period ;
 
 Fitting is done using a Bayesian-like framework, where the user can specify the likelihood of observed outcomes in data given modeled outcomes, and the priors on any parameters to be fit. Multiple data streams (e.g., cases and deaths) can be fit simultaneously. A custom Markov Chain Monte Carlo method is used to sequentially propose and accept or reject parameter values based on the model fit to data, in a way that balances fit quality within each individual subpopulation with that of the total aggregate population, and that takes advantage of parallel computing environments.
 
-The code is written in a combination of [R](https://www.r-project.org/) and [Python](https://www.python.org/), and the vast majority of users only need to interact with the pipeline via the components written in R. It is structured in a modular fashion, such that individual components – such as the epidemic model, the observable variables, the population structure, or the parameters – can be edited or completely replaced without any handling of other parts of the code. 
+The code is written in a combination of [R](https://www.r-project.org/) and [Python](https://www.python.org/), and the vast majority of users only need to interact with the pipeline via the components written in R. It is structured in a modular fashion, such that individual components – such as the epidemic model, the observable variables, the population structure, or the parameters – can be edited or completely replaced without any handling of other parts of the code ;
 
 When model simulation is combined with fitting to data, the code is designed to run most efficiently on a supercomputing cluster with many cores. We most commonly run the code on [Amazon Web Services](https://aws.amazon.com/) or on high-performance computers using SLURM. However, even relatively large models can be run efficiently on most personal computers. Typically, the memory of the machine will limit the number of compartments (i.e., variables) that can be included in the epidemic model, while the machine’s CPU will determine the speed at which each model run is completed and the number of iterations of the model that can be run during parameter searches when fitting the model to data. While the pipeline can be installed on any computer, it is sometime easier to use an Anaconda environment or the provided [Docker](https://www.docker.com/) container, where all the software dependencies (e.g., standardized R and Python versions along with required packages) are included, independent of the user’s local machine. All the code is maintained on [our GitHub](https://github.com/HopkinsIDD/flepiMoP) and shared with the GNU General Public License v3.0 license. It is build on top of a fully open-source software stack.
 
@@ -47,7 +47,7 @@ For questions about the pipeline or to report a bug, please use the “Issues”
 
 ### Acknowledgments
 
-_flepiMoP_ is actively developed by its current contributors, including Joseph C Lemaitre, Sara L Loo, Emily Przykucki, Clifton McKee, Claire Smith, Sung-mok Jung, Koji Sato, Pengcheng Fang, Erica Carcelen, Alison Hill, Justin Lessler, and Shaun Truelove, affiliated with the: 
+_flepiMoP_ is actively developed by its current contributors, including Joseph C Lemaitre, Sara L Loo, Emily Przykucki, Clifton McKee, Claire Smith, Sung-mok Jung, Koji Sato, Pengcheng Fang, Erica Carcelen, Alison Hill, Justin Lessler, and Shaun Truelove, affiliated with the ;
 
 * Department of Epidemiology, Gillings School of Global Public Health, University of North Carolina at Chapel Hill, Chapel Hill, NC, USA for (JCL, JL)
 * Johns Hopkins University International Vaccine Access Center, Department of International Health, Baltimore, MD, USA for (SLL, KJ, EC, ST)

documentation/gitbook/SUMMARY.md

@@ -9,8 +9,10 @@
   * [flepiMoP's configuration file](gempyor/model-implementation/introduction-to-configuration-files.md)
   * [Specifying population structure](gempyor/model-implementation/specifying-population-structure.md)
   * [Specifying compartmental model](gempyor/model-implementation/compartmental-model-structure.md)
-  * [Specifying initial conditions and seeding](gempyor/model-implementation/specifying-initial-conditions-and-seeding.md)
+  * [Specifying initial conditions](gempyor/model-implementation/specifying-initial-conditions.md)
+  * [Specifying seeding](gempyor/model-implementation/specifying-seeding.md)
   * [Specifying observational model](gempyor/model-implementation/outcomes-for-compartments.md)
+  * [Distributions](gempyor/model-implementation/distributions.md)
   * [Specifying time-varying parameter modifications](gempyor/model-implementation/intervention-templates.md)
   * [Other configuration options](gempyor/model-implementation/other-configuration-options.md)
   * [Code structure](gempyor/model-implementation/code-structure.md)
@@ -52,28 +54,24 @@
   * [Running on AWS 🌳](how-to-run/advanced-run-guides/running-on-aws.md)
 * [Common errors](how-to-run/common-errors.md)
 * [Useful commands](how-to-run/useful-commands.md)
+* [Tips, tricks, FAQ](how-to-run/tips-tricks-faq.md)
 
 ## 🗜️ Development
 
-* [Python guidelines for developers](development/python-guidelines-for-developers.md)
+* [Guidelines for contributors](development/python-guidelines-for-developers.md)
 
 ## Deprecated pages
 
-* [Running with RStudio Server on AWS EC2](deprecated-pages/running-with-rstudio-server-on-aws-ec2.md)
-* [Running with docker on AWS - OLD probably outdated](deprecated-pages/running-with-docker-on-aws/README.md)
-  * [Provisioning AWS EC2 instance](deprecated-pages/running-with-docker-on-aws/provisioning-aws-ec2-instance.md)
-  * [AWS Submission Instructions: Influenza](deprecated-pages/running-with-docker-on-aws/aws-submission-instructions-influenza.md)
-  * [AWS Submission Instructions: COVID-19](deprecated-pages/running-with-docker-on-aws/aws-submission-instructions-covid-19.md)
 * [Module specification](deprecated-pages/module-specification.md)
-* [Block that don't go anywhere](deprecated-pages/block-that-dont-go-anywhere.md)
 
 ## JHU Internal
 
 * [US specific How to Run](jhu-internal/us-specific-how-to-run/README.md)
   * [Running with Docker locally (outdated/US specific) 🛳](jhu-internal/us-specific-how-to-run/running-with-docker-locally.md)
   * [Running on Rockfish/MARCC - JHU 🪨🐠](jhu-internal/us-specific-how-to-run/slurm-submission-on-marcc.md)
+  * [Running with docker on AWS - OLD probably outdated](jhu-internal/us-specific-how-to-run/running-with-docker-on-aws/README.md)
+    * [Provisioning AWS EC2 instance](jhu-internal/us-specific-how-to-run/running-with-docker-on-aws/provisioning-aws-ec2-instance.md)
+    * [AWS Submission Instructions: Influenza](jhu-internal/us-specific-how-to-run/running-with-docker-on-aws/aws-submission-instructions-influenza.md)
+    * [AWS Submission Instructions: COVID-19](jhu-internal/us-specific-how-to-run/running-with-docker-on-aws/aws-submission-instructions-covid-19.md)
+  * [Running with RStudio Server on AWS EC2](jhu-internal/us-specific-how-to-run/running-with-rstudio-server-on-aws-ec2.md)
 * [Inference scratch](jhu-internal/inference-scratch.md)
-
-## Group 1
-
-* [Page 1](group-1/page-1.md)