Add option to save internal variables during SI-simulation

[franksh]

Currently only some variables of the SI-simulation are saved and accessible via the Python-API: The time (SI.time), number of infected (SI.I) and a list of susceptible-infected contacts (SI.SI).

It would be nice to have to option to save more detailed internal variables, such as a list of infection events, such that for instance information on transmission chains is extractable. These variables are currently computed during the simulation but not kept for memory efficiency.

The option could be added to the tc.SI() interface as a flag save_internal_variables=True/False

[benmaier]

In SI.h, please add a property to save the infection events, e.g.

vector < pair < size_t, size_t > > infection_events

at https://github.com/benmaier/tacoma/blob/master/_tacoma/SI.h#L185

Every time an infection event is triggered, just push a pair of the infecting and infected node id.

Add a flag to the init routine at https://github.com/benmaier/tacoma/blob/master/_tacoma/SI.h#L71 and make this flag available to the Python interface at https://github.com/benmaier/tacoma/blob/master/_tacoma/_tacoma.cpp#L1050 .

Add the private attribute save_internal_variable here https://github.com/benmaier/tacoma/blob/master/_tacoma/SI.h#L56 .

An infection event is triggered here https://github.com/benmaier/tacoma/blob/master/_tacoma/SI.cpp#L144

Just add a few lines of code where the infecting-infected pair is pushed to infection_events if demanded by the private flag save_internal_variables.

Make the public attribute infection_events available to Python by adding the attribute here https://github.com/benmaier/tacoma/blob/master/_tacoma/_tacoma.cpp#L1074 .

You can also add this flag to the docstring https://github.com/benmaier/tacoma/blob/master/_tacoma/_tacoma.cpp#L1067

[franksh]

I'm implementing the changes at the moment. I noticed that the actual memory demand of the new variable won't be big. At the moment the code saves the time when an event occurs, as well as the observables SI and I, which are each vector <size_t>. The new variable infection events will be of similar size. Should I still include the flag save_infection_events or just include it by default without the option to change?

[franksh]

Btw I noticed that the docstrings at https://github.com/benmaier/tacoma/blob/master/_tacoma/_tacoma.cpp#L1074 for S, I are not correct, same in the SIS model. I will fix them with this pull request.

[benmaier]

I thought about this and think that for standard simulations (analysis of prevalence curves) one would only need I (not even SI) and everything else should be unnecessary. For this reason I'd prefer the flag as not to clutter the result classes.

Granted following this logic SI should get an own flag, too ... but I'd rather think about it later and keep it like this for the moment.

Cheers for fixing the docstrings!