R/generate_function_documentation.R

In andreashandel/modelbuilder: Building Compartmental Simulation Models Without Coding

#' Create documentation/header part for a simulation model
#'
#' This function takes as input a modelbuilder model and writes code
#' that produces the header part used in the functions that create model code
#'
#' @description The model needs to adhere to the structure specified by the modelbuilder package.
#' Models built using the modelbuilder package automatically have the right structure.
#' A user can also build a model list structure themselves following the modelbuilder specifications.
#' If the user provides a file name, this file needs to be an Rds file
#' and contain a valid modelbuilder model structure.
#' @param mbmodel modelbuilder model structure
#' @param modeltype Indicates type of model code that is generated. One of ode/stochastic/discrete
#' @return text that to be placed on top of function code generated by the calling function
#' @export

generate_function_documentation <- function(mbmodel, modeltype)
{

    if (modeltype == "ode")
    {
        modeltypetext = "#' The model is implemented as a set of ordinary differential equations using the deSolve package. \n#' The following R packages need to be loaded for the function to work: deSolve. \n#' \n"
    }
    if (modeltype == "stochastic")
    {
        modeltypetext = "#' The model is implemented as a set of stochastic equations using the adaptivetau package. \n \n#' The following R packages need to be loaded for the function to work: adpativetau \n#' \n"

    }
    if (modeltype == "discrete")
    {
        modeltypetext = "#' The model is implemented as a set of discrete time equations using a for loop. \n \n#' The following R packages need to be loaded for the function to work: none \n#' \n"
    }

    nvars = length(mbmodel$var)  #number of variables/compartments in model
    npars = length(mbmodel$par)  #number of parameters in model
    ntime = length(mbmodel$time) #numer of parameters for time
    #text for model description
    #all this should be provided in the model structure
    sdesc=paste0("#' ",mbmodel$title,"\n#' \n")
    sdesc=paste0(sdesc,"#' @description ",mbmodel$description,"\n#' \n")
    sdesc=paste0(sdesc,"#' @details ",mbmodel$details, "\n")
    sdesc=paste0(sdesc,"#' \n")
    sdesc=paste0(sdesc,"#' This code was generated by the modelbuilder R package.  \n")
    sdesc=paste0(sdesc, modeltypetext)

    #text for all starting values for variables
    #note that those are parameters for the function
    varstring = "" #will be used below to construct example
    for (n in 1:nvars)
    {
        sdesc=paste0(sdesc,"#' @param ", mbmodel$var[[n]]$varname, ' : starting value for ',mbmodel$var[[n]]$vartext," : numeric", "\n")
        varstring = paste0(varstring,mbmodel$var[[n]]$varname, " = ", 2*mbmodel$var[[n]]$varval,",")
    }
    varstring = substr(varstring,1,nchar(varstring)-1) #get rid of final comma

    #mbmodel parameters, also function parameters
    for (n in 1:npars)
    {
        sdesc=paste0(sdesc,"#' @param ", mbmodel$par[[n]]$parname," : ", mbmodel$par[[n]]$partext," : numeric", "\n")
    }

    # Have start/final and timestep for ODE and discrete.
    # No start time and time step for adaptivetau/stochastic since that's not supported
    # stochastic also needs random number seed
    if (modeltype != "stochastic")
    {
        for (n in 1:ntime)
        {
           sdesc=paste0(sdesc,"#' @param ", mbmodel$time[[n]]$timename," : ", mbmodel$time[[n]]$timetext," : numeric", "\n")
        }
    } else if (modeltype == "stochastic") #for stochastic model, only use tfinal, no tstart and dt
    {
        sdesc=paste0(sdesc,"#' @param ", mbmodel$time[[2]]$timename," : ", mbmodel$time[[2]]$timetext," : numeric", "\n")
        sdesc=paste0(sdesc,"#' @param rngseed : set random number seed for reproducibility : numeric", "\n")
    }


    sdesc=paste0(sdesc,"#' @return The function returns the output as a list. \n")
    sdesc=paste0(sdesc,"#' The time-series from the simulation is returned as a dataframe saved as list element \\code{ts}. \n")
    sdesc=paste0(sdesc,"#' The \\code{ts} dataframe has one column per compartment/variable. The first column is time.   \n")
    sdesc=paste0(sdesc,"#' @examples  \n")
    sdesc=paste0(sdesc,"#' # To run the simulation with default parameters:  \n")
    sdesc=paste0(sdesc,"#' result <- simulate_",gsub(" ","_",mbmodel$title),"_",modeltype,"()", " \n")
    sdesc=paste0(sdesc,"#' # To choose values other than the standard one, specify them like this:  \n")
    sdesc=paste0(sdesc,"#' result <- simulate_",gsub(" ","_",mbmodel$title),"_",modeltype,"(",varstring,") \n")
    sdesc=paste0(sdesc,"#' # You can display or further process the result, like this:  \n")
    sdesc=paste0(sdesc,"#' plot(result$ts[,'time'],result$ts[,'",mbmodel$var[[1]]$varname,"'],xlab='Time',ylab='Numbers',type='l') \n")
    sdesc=paste0(sdesc,"#' print(paste('Max number of ",mbmodel$var[[1]]$varname,": ',max(result$ts[,'",mbmodel$var[[1]]$varname,"']))) \n")

    sdesc=paste0(sdesc,"#' @section Warning: ","This function does not perform any error checking. So if you try to do something nonsensical (e.g. have negative values for parameters), the code will likely abort with an error message.", "\n")
    sdesc=paste0(sdesc,"#' @section Model Author: ",mbmodel$author, "\n")
    sdesc=paste0(sdesc,"#' @section Model creation date: ",mbmodel$date, "\n")
    sdesc=paste0(sdesc,"#' @section Code Author: generated by the \\code{modelbuilder} R package \n")
    sdesc=paste0(sdesc,"#' @section Code creation date: ",Sys.Date(), "\n")
    sdesc=paste0(sdesc,"#' @export \n \n")

    return(sdesc)

}