Merge branch 'main' of https://github.com/canmod/macpan2

inst/starter_models/flow_examples/README.md

@@ -0,0 +1,5 @@
+---
+title: "Flow types model"
+index_entry: "A model to demonstrate all flow types"
+author: Darren Flynn-Primrose
+---

inst/starter_models/flow_examples/derivations.json

@@ -0,0 +1 @@
+[]

inst/starter_models/flow_examples/flows.csv

@@ -0,0 +1,7 @@
+from ,to ,flow  ,type       ,from_partition ,to_partition ,flow_partition ,from_to_partition ,from_flow_partition ,to_flow_partition
+Dummy,A,absin,absolute_inflow,Main,Main,Main,,,Null
+A,Dummy,absout,absolute_outflow,Main,Main,Main,,,Null
+A,B,abs,absolute,Main,Main,Main,,,Null
+B,C,percap,per_capita,Main,Main,Main,,,Null
+C,Dummy,percapout,per_capita_outflow,Main,Main,Main,,,Null
+C,D,percapin,per_capita_inflow,Main,Main,Main,,,Null

inst/starter_models/flow_examples/settings.json

@@ -0,0 +1,6 @@
+{
+  "required_partitions" : ["Main"],
+  "null_partition" : ["Null"],
+  "state_variables" : ["A", "B", "C", "D", "Dummy"],
+  "flow_variables" : ["absin", "absout", "abs", "percap", "percapin", "percapout"]
+}

inst/starter_models/flow_examples/variables.csv

@@ -0,0 +1,15 @@
+Main
+A
+B
+C
+D
+Dummy
+absin
+absout
+abs
+percap
+percapout
+percapin
+
+
+

vignettes/flow_types.Rmd

@@ -24,3 +24,56 @@ knitr::opts_chunk$set(
 )
 cat_file = function(...) cat(readLines(file.path(...)), sep = "\n")
 ```
+
+## Types of Flows
+The `Macpan2` library allows for six different types of flows. They are:
+
+1. `per_capita` 
+2. `absolute`
+3. `per_capita_inflow`
+4. `per_capita_outflow`
+5. `absolute_inflow`
+6. `absolute_outflow`
+
+There is also a demo model with one flow of each type.
+
+```{R}
+flow_example_dir = system.file("starter_models", "flow_examples", package = "macpan2")
+flow_example = Compartmental(flow_example_dir)
+flow_example$labels$state()
+flow_example$labels$flow()
+flow_example$flows()
+```
+
+Modelers can specify the type of a given flow in the `type` column of the `flows.csv` file.
+
+## per_capita Flows
+
+Probably the most common type of flow `per_capita` flows move a given proportion of the population in the `from` compartment to the `to` compartment. For example if two compartments `A` and `B` have populations `P_a` and `P_b` respectively and are linked by a per_capita flow with flow rate `r` then the population of `A` will decrease by `P_a * r` per unite time and the population of `B` will increase by an equal amount. So after a single time step the population of `A` will be `P_a - P_a * r` and the population of `B` will be `P_b + P_a * r`.
+
+## Absolute Flows
+
+Unlike per_capita flows, absolute flows specify the change in compartmental populations in absolute terms. If compartments `A` and `B` are connected by an absolute flow with rate `r` then the population of `A` will decrease by `r` per unite time and the population of `B` will increase by an equal amount. Thus after a single time step the population of `A` will be `P_a - r` and the population of `B` will be `P_b + r`.
+
+## Inflows and Outflows
+
+Flows can also be specified as `inflows` or ` outflows`. Inflows increase the population of their `to` compartment but have no effect on the population of their `from` compartment. Similarly outflows decrease the population of their `from` compartment but do not have any `to` compartment. Inflows and outflows can be either `per_capita` flows or `absolute` flows. For example if `A` is a compartment with an `absolute_outflow` and a flow rate `r` then after a single time step `A` will have a population of `P_a -r`. Since outflows have no `to` compartment the population that is removed from `A` is not added anywhere, the total population of the model will decrease by `r`. Alternatively, if `B` is a compartment with a `per_capita_inflow` with rate `r` and `from` compartment `A` then the population of `B` will increase by `P_a * r` per unite time. Notably, the population of `A` will not be changed so the total population of the model will increase. After a single time step the population of `B` will be `P_b + P_a * r` and the population of `A` will be `P_a` (baring the influence of any other flows `A` might have).
+
+## Specific Example
+
+We have created an example model which includes each type of flow. One key detail is that Macpan2 currently requires all flows in the `flows.csv` file to have both an `from` and `to` compartment. [See here](https://github.com/canmod/macpan2/issues/56). This includes for `absolute_inflows` which have no `from` compartment as well as `absolute_outflows` and `per_capita_outflows` which have no `to` compartments. In this example we have explicitly used a dummy compartment to fulfill the requirement, in principle any compartment can be used as a dummy compartment since no actual changes to that compartments population will result from being used in this way. Note that `per_capita_inflows` do require a `from` compartment as the population of that compartment will be use to compute the total inflow to the `to` compartment. As with the other one-sided flows though `per_capita_inflows` do not change the population of their `from` compartment.
+
+``` {R sim_values}
+ flow_simulator = flow_example$simulators$tmb(
+   time_steps = 10,
+   state = c(A = 1000, B = 0, C = 0, D = 0, Dummy = 0),
+   flow = c(absin = 1000, absout = 500, abs = 100, percap = 0.5, percapout = 0.25, percapin=0.25)
+ )
+```
+
+ Because this model includes absolute flows it is important to chose starting values carefully to prevent state populations from going below zero.
+
+```{R run_sims}
+ flow_results = flow_simulator$report()
+ head(flow_results, 16)
+```