nicer edge labels in `visCompartment()`

[papsti]

would be nice for the visNetwork graphic to read the flow type from sir$flows() and generate an edge label with the full flow.

for instance, for the sample SIR model, we have

sir$flows()
  from to  flow       type
1    S  I   foi per_capita
2    I  R gamma per_capita

currently, the edges of the compartmental graph are labelled simply with the entry in flow. it would be clearer if these flows were labelled with the compound entry flow * from (since type is per_capita). we'd have to write a labeller based on type.

[stevencarlislewalker]

Here are some of my thoughts on this topic in case they are useful.

I have come to give flow variable names that are descriptive of the flow itself, and not just the variable used to quantify flow magnitude. So for example instead of foi I would now put infection and instead of gamma I would now put recovery. The names foi and gamma are tied to the flow type as you suggest, but the names infection and recovery are not in my opinion and just describe the flow mechanism and therefore are good things to have on the diagram.

On the other hand it could be a bad thing that the label infection does double-duty as a quantification of flow magnitude and as a description of the flow mechanism. If this is how we feel then I believe that it would be 'better' to add an optional field to the flows.csv spec called mechanism, where we would put things like infection and recovery. And then these mechanisms could be plotted on the diagram.

On the other other hand maybe people disagree with me and do not want mechanism names but rather do in fact want something like foi * S.

On the other other other hand maybe we want to colour the edges with a legend giving the flow types.

[papsti]

this is an interesting point... so is your new approach to have a flows.csv like

from ,to ,flow      ,type
S    ,I  ,infection ,absolute

and then have a derivations.json like

[
    {
     "output_names": ["infection"],
     "simulation_phase": "during_pre_update",
     "arguments": ["S", "I", "beta", "N"],
     "expression": "I * beta / N * S"
    }
]

?

i believe this would also mean that variables.csv would have to look like

Epi
S
I
R
N
beta
infection
gamma

just checking that i understood what you were saying in that second paragraph.

if so, i agree this would make a tidier automatic diagram, but this paradigm would de-incentivize the use of the "per-capita" flow rate type, so i'm partial to your suggestion of instead adding a label ("mechanism") column.

however, i wouldn't add a label column in flows.csv or change the macpan2 spec in any way. i would instead amend the visCompartment() function to label using the flow column of flows.csv unless an additional flow_label column is provided in the input, and if it is, use that. this way the user can customize the vis without us having to change the macpan2 inputs for something that only macpan2helpers would use.

i could also make a utility that generates nice labels column using the flow type column with a call to dplyr::mutate, which i guess is kind of what i was suggesting all along 🙃