Adding documentations assets

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/assets/s_22mr22/s_22mr22.prj

@@ -0,0 +1 @@
+GEOGCS["GCS_North_American_1983",DATUM["D_North_American_1983",SPHEROID["GRS_1980",6378137.0,298.257222101]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]]

documentation/gitbook/SUMMARY.md

@@ -9,7 +9,8 @@
   * [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)
   * [Specifying time-varying parameter modifications](gempyor/model-implementation/intervention-templates.md)
   * [Other configuration options](gempyor/model-implementation/other-configuration-options.md)
@@ -55,7 +56,7 @@
 
 ## 🗜️ Development
 
-* [Python guidelines for developers](development/python-guidelines-for-developers.md)
+* [Guidelines for contributors](development/python-guidelines-for-developers.md)
 
 ## Deprecated pages
 

documentation/gitbook/development/python-guidelines-for-developers.md

@@ -1,10 +1,37 @@
-# Python guidelines for developers
+# Guidelines for contributors
 
-The "heart" of the pipeline, gempyor, is written in python taking advantage of just-in-time compilation (via numba) and existing optimized librairies (numpy, pandas). If you would like to help us build gempyor, here are some useful information
+All are welcome to contribute to flepiMoP! The easiest way is to open an issue on GitHub if you encounter a bug or if you have an issue with the framework. We would be very happy to help you out.
 
-### Tests and build dependencies
+If you want to contribute code, fork the [flepiMoP repository](https://github.com/HopkinsIDD/flepiMoP), modify it, and submit your Pull Request (PR). In order to be merged, a pull request need:
 
-First, you'll need to install the gempyor package with build dependencies:
+* the approval of two reviewers AND
+* the continuous integration (CI) tests passing.
+
+### Contributing to the Python code
+
+The "heart" of the pipeline, gempyor, is written in Python taking advantage of just-in-time compilation (via `numba`) and existing optimized libraries (`numpy`, `pandas`). If you would like to help us build gempyor, here is some useful information.
+
+#### Frameworks
+
+We make extensive use of the following packages:
+
+* [click](https://click.palletsprojects.com/en/) for managing the command-line arguments
+* [confuse](https://confuse.readthedocs.io/en/latest/usage.html) for accessing the configuration file
+* numba to just-in-time compile the core model
+* sympy to parse the model equations
+* pyarrow as parquet is our main data storage format
+* [xarray](https://docs.xarray.dev/en/stable/), which provides labels in the form of dimensions, coordinates and attributes on top of raw NumPy multidimensional arrays, for performance and convenience. 
+* emcee for inference, as an option
+* graphviz to export transition graph between compartments
+* pandas, numpy, scipy, seaborn, matplotlib and tqdm like many Python projects
+
+{% hint style="info" %}
+One of the current focus is to switch internal data types from dataframes and numpy array to xarrays!
+{% endhint %}
+
+#### Tests and build dependencies
+
+To run the tests suite locally, you'll need to install the gempyor package with build dependencies:
 
 ```bash
 pip install "flepimop/gempyor_pkg[test]"
@@ -14,15 +41,15 @@ which installs the `pytest` and `mock` packages in addition to all other gempyor
 
 If you are running from a conda environment and installing with \`--no-deps\`, then you should make sure that these two packages are installed.
 
-Now you can try to run the gempyor test suite by running, from the `gempyor_pkg` folder:
+Now you can try to run the gempyor test suite by running, from the `flepimop/gempyor_pkg` folder:
 
 ```bash
 pytest
 ```
 
 If that works, then you are ready to develop gempyor. Feel free to open your first pull request.
 
-If you want more output on tests, e.g capturing standart output (print), you can use:
+If you want more output on tests, e.g capturing standard output (print), you can use:
 
 ```bash
 pytest -vvvv
@@ -40,7 +67,7 @@ Before committing, make sure you **format your code** using black (see below) an
 
 ### Formatting
 
-We try to remain close to python conventions and to follow the updated rules and best practices. For formatting, we use [black](https://github.com/psf/black), the _Uncompromising Code Formatter_ before submitting pull-requests. It provides a consistent style, which is useful when diffing. We use a custom length of 120 characters as the baseline is short for scientific code. Here is the line to use to format your code:
+We try to remain close to Python conventions and to follow the updated rules and best practices. For formatting, we use [black](https://github.com/psf/black), the _Uncompromising Code Formatter_ before submitting pull requests. It provides a consistent style, which is useful when diffing. We use a custom length of 120 characters as the baseline is short for scientific code. Here is the line to use to format your code:
 
 ```bash
 black --line-length 120 . --exclude renv*
@@ -50,10 +77,22 @@ black --line-length 120 . --exclude renv*
 Please use type-hints as much as possible, as we are trying to move towards static checks.
 {% endhint %}
 
-### Structure of the main classes
+#### Structure of the main classes
+
+The code is structured so that each of the main classes **owns** a config segment, and only this class should parse and build the related object. To access this information, other classes first need to build the object.
+
+{% hint style="warning" %}
+Below, this page is still underconstruction
+{% endhint %}
 
-The main classes, such as `Parameter`, `NPI`, `SeedingAndInitialConditions`,`Compartments` should tend to the same struture:
+The main classes are:
 
+* `Coordinates:` this is a light class that stores all the coordinates needed by every other class (e.g the time serie
+* `Parameter`
+* `Compartments`
+* `Modifers`
+* `Seeding`,
+* `InitialConditions`
 * a `writeDF`
 * function to plot
 * (TODO: detail pipeline internal API)

documentation/gitbook/gempyor/model-implementation/compartmental-model-structure.md

@@ -530,6 +530,13 @@ Note that there is an alternative way to specify time dependence in parameter va
 
 Compartmental model parameters can have an additional attribute beyond `value` or `timeseries`, which is called `stacked_modifier_method`. This value is explained in the section on coding [`time-dependent parameter modifications`](intervention-templates.md) (also known as "modifiers") as it determines what happens when two different modifiers act on the same parameter at the same time (are they combined additively or multiplicatively?). 
 
+| Config item               | Required?                              | Type/Format                                   | Description                                                                               |
+| ------------------------- | -------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `value`                   | either value or timeseries is required | numerical, or distribution                    | This defines the value of the parameter, as described above.                              |
+| `timeseries`              | either value or timeseries is required | path to a csv file                            | This defines a timeseries for each day, as above.                                         |
+| `stacked_modifier_method` | optional                               | string: `sum`, `product`, `reduction_product` | This option defines the method used when modifiers are applied. The default is `product`. |
+| `rolling_mean_windows`    | optional                               | integer                                       | The size of the rolling mean window if a rolling mean is applied.                         |
+
 ## Specifying model simulation method `(seir::integration)`
 
 A compartmental model defined using the notation in the previous sections describes rules for classifying individuals in the population based on infection state dynamically, but does not uniquely specify the mathematical framework that should be used to simulate the model.

documentation/gitbook/gempyor/model-implementation/introduction-to-configuration-files.md

@@ -90,15 +90,15 @@ This section is where users can specify the details of the infectious disease tr
 Optional section
 {% endhint %}
 
-This section is used to specify the initial conditions of the model, which define how individuals are distributed between the model compartments at the time the model simulation begins. Importantly, the initial conditions specify the time and location where infection is first introduced. If this section is omitted, default values are used. If users want to add infections to the population at later times, or add or remove individuals from compartments separately from the model rules, they can do so via the related `seeding` section. More details [here](specifying-initial-conditions-and-seeding.md). 
+This section is used to specify the initial conditions of the model, which define how individuals are distributed between the model compartments at the time the model simulation begins. Importantly, the initial conditions specify the time and location where infection is first introduced. If this section is omitted, default values are used. If users want to add infections to the population at later times, or add or remove individuals from compartments separately from the model rules, they can do so via the related `seeding` section. More details [here](specifying-initial-conditions.md). 
 
 ### `seeding` section
 
 {% hint style="info" %}
 Optional section
 {% endhint %}
 
-This section is used to specify how individuals are instantaneously "seeded" from one compartment to another, where they then continue to be governed by the model equations. For example, this seeding could be used to represent importations of infected individuals from an outside population, mutation events that create new strains, or vaccinations that alter disease susceptibility. Seeding events can occur at any time in the simulation. The seeding section specifies the numeric values added to or removed from any compartment of the model. More details [here](specifying-initial-conditions-and-seeding.md). 
+This section is used to specify how individuals are instantaneously "seeded" from one compartment to another, where they then continue to be governed by the model equations. For example, this seeding could be used to represent importations of infected individuals from an outside population, mutation events that create new strains, or vaccinations that alter disease susceptibility. Seeding events can occur at any time in the simulation. The seeding section specifies the numeric values added to or removed from any compartment of the model. More details [here](specifying-initial-conditions.md). 
 
 ### `outcomes` section