Helper function for running over different values of single parameter

[adamkucharski]

I was recently adapting finalsize with some collaborators to explore disease re-emergence from demographic turnover and waning (will write up as vignette when get a minute), and used some of the nice walkthrough in epidemics vignette as starting point.

But it make me realise it's still a bit of a pain for users to generate multiple outputs varying over a single parameter and output as neat data.frame (this is something I've spent a lot of time coding up clunky loops for in the past). It feels like a function like the below could be very helpful to streamline examples in tutorials and vignettes. Although it's a wrapper over Map and Reduce, I think there's enough non-obvious steps for a moderate R user to justify some simplification in a summary function.

The question is where it should sit (e.g. helper function package, or in one dependency-light package like {quickfit} that we then make available to others in vignettes)? Would be interested in thoughts @pratikunterwegs @joshwlambert @Bisaloo.

# Define Map/Reduce function to output data.frame
run_multiple <- function(input_vector,
                         input_fn){
  
  # use map to run over values
  output <- Map(
    function(xx, i) {
      f_out <- input_fn(xx) # run input function
      data.frame(i = i, param = xx, function_out = f_out) # data.frame for each value considered
    }, 
    xx = input_vector, 
    i = seq_along(input_vector)
  )
  
  # combine the list of data.frames into a single data.frame
  output_df <- Reduce(rbind, output)
  
  output_df
  
}



# Define inputs for finalsize example
library(finalsize)
input_vector <- rnorm(n = 100, mean = r0_mean, sd = 0.1)
input_fn <- function(x){final_size(x)$p_infected}

# Run function
finalsize_df <- run_multiple(input_vector,input_fn)

[TimTaylor]

@adamkucharski - Related discussions ongoing in {epidemics} epiverse-trace/epidemics#160

[adamkucharski]

Thanks for flagging. Think this is something that will come up both within package functions (e.g. stochastic realisations) and across (e.g. looping over parameters, which many of our packages will use). Not clear to me where the latter would best sit.

[TimTaylor]

I'm not sure about additional functions here as input/output can vary so much and not sure you gain too much over a lapply or mapply approach (possibly combined with a nested tibble if needed).

out <- lapply(x, fun, par2 = a)
tibble(input = x, output = out)

I think there is a conversation to be had on functions where you expect individuals to run over multiple inputs and whether there is then a benefit (e.g. ergonomics, efficiency, capturing warnings / errors ) to take vector inputs.

[Bisaloo]

Within the tidyverse, pmap_dfr() is also an alternative that will do the loop and combine steps in one function call. It's soft deprecated but probably not going to go away.

[adamkucharski]

There will be lots of situations where the input/output will be predictable (i.e. single number input and single number output) – I've probably had this basic use case in most outbreak/epidemic analyses I've worked on. I think the drawback with the above lapply (and similar options) is that it's immediately creating a technical hurdle for users to do anything with model outputs, because the output column is a list (so user will need to unlist somewhere, plus take on tibble as dependency).

I wouldn't underestimate value of users being able to get a handy output in one easy function rather than a string of ones that require more thought!

[TimTaylor]

There will be lots of situations where the input/output will be predictable (i.e. single number input and single number output)

For functions that are scalar in/out out I'd really consider taking vector inputs and giving vector output though. This way the users don't need any extra functions. Also for these you still have sapply(x, fun) if they are not vectorised.

Either way - worth more discussion

[adamkucharski]

In an ideal world, that would be a nicer solution for users (especially for simpler functions). Although suspect it would require a lot of internal changes to simulation-based models in packages to handle input vectors by default (or would need to have a version of function like the above in all our model calls)?

So perhaps a neat one-line alternative function for users that does it outside the model is a reasonable compromise?

[pratikunterwegs]

Thanks @adamkucharski for starting this discussion. @TimTaylor, @Bisaloo and I will have a meeting tomorrow at 10:15 GMT to discuss options for an API that works towards this.