Types of Flows
The Macpan2 library allows for six different types of
flows. They are:
per_capitaabsoluteper_capita_inflowper_capita_outflowabsolute_inflowabsolute_outflow
There is also a demo model with one flow of each type.
flow_example_dir = system.file("starter_models", "flow_examples", package = "macpan2")
flow_example = Compartmental(flow_example_dir)
flow_example$labels$state()
#> [1] "A" "B" "C" "D" "Dummy"
flow_example$labels$flow()
#> [1] "absin" "absout" "abs" "percap" "percapin" "percapout"
flow_example$flows()
#> from to flow type from_partition to_partition
#> 1 Dummy A absin absolute_inflow Main Main
#> 2 A Dummy absout absolute_outflow Main Main
#> 3 A B abs absolute Main Main
#> 4 B C percap per_capita Main Main
#> 5 C Dummy percapout per_capita_outflow Main Main
#> 6 C D percapin per_capita_inflow Main Main
#> flow_partition from_to_partition from_flow_partition to_flow_partition
#> 1 Main Null
#> 2 Main Null
#> 3 Main Null
#> 4 Main Null
#> 5 Main Null
#> 6 Main NullModelers 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. 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.
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.
flow_results = flow_simulator$report()
head(flow_results, 16)
#> matrix time row col value
#> 1 state 0 A 1000
#> 2 state 0 B 0
#> 3 state 0 C 0
#> 4 state 0 D 0
#> 5 state 0 Dummy 0
#> 6 state 1 A 1400
#> 7 state 1 B 100
#> 8 state 1 C 0
#> 9 state 1 D 0
#> 10 state 1 Dummy 0
#> 11 state 2 A 1800
#> 12 state 2 B 150
#> 13 state 2 C 50
#> 14 state 2 D 0
#> 15 state 2 Dummy 0
#> 16 state 3 A 2200