microPopModel {microPop}

Runs the microbial population model

Description

creates a system of ordinary differential equations and solves them

Usage

microPopModel(
  microbeNames,
  times,
  resourceSysInfo,
  microbeSysInfo,
  rateFuncs = rateFuncsDefault,
  odeFunc = derivsDefault,
  numStrains = 1,
  oneStrainRandomParams = FALSE,
  pHLimit = FALSE,
  pHVal = NA,
  plotOptions = list(),
  odeOptions = list(),
  strainOptions = list(),
  checkingOptions = list(),
  microbeMolarMass = 113,
  bacCutOff = 1e-14,
  networkAnalysis = FALSE,
  myPars = NULL,
  ...
)

Arguments

microbeNames

Vector of strings which contains the names of the microbial groups in the system e.g. c('Bacteroides','Acetogens'). A dataframe for each of the same name must also exist in the workspace.

times

Vector of times at which the solution is required, e.g. seq(0,10,0.1)

resourceSysInfo

String giving the name of a csv file or a dataframe object, which describes the initial conditions, inflow and outflow (if constant) and molar mass of each resource. See help(resourceSysInfo) for more info.

microbeSysInfo

String giving the name of a csv file (e.g. 'systemInfoMicrobes.csv') or a dataframe object, which describes the initial conditions, inflow and outflow (if constant) of each microbial group. See help(microbeSysInfo) for more info.

rateFuncs

A list of functions which are used to solve the ODEs in odeFunc. Default is rateFuncsDefault.R (provided in the package). See ?rateFuncs

odeFunc

The function the ODE solver will use - the default is derivsDefault provided by the package but if the user wants to make significant changes a new ODE function file can be used. See ?derivsDefault

numStrains

Integer (or named vector of integers) stating the number of strains in each microbial group. If this is a single number it is the same for all groups. If it is a vector it must be named using microbeNames. Default is 1.

oneStrainRandomParams

Logical to allow randomization of parameters even if there is only one strain. The default is FALSE which means that if numStrains=1 then the group params are used; if numStrains>1 then the parameters are automatically randomised according to info given in strainOptions. If oneStrainRandomParams=TRUE then even if there is only one strain its parameters will be randomised according to info given in strainOptions.

pHLimit

TRUE if pH limits microbial growth rates. Default is FALSE. If TRUE then rateFuncs$pHLimFunc is called.

pHVal

Scalar. If the pH value is fixed it can be specified here and this is then used in the default rateFuncs$pHFunc function.

plotOptions

List containing instructions for plotting: Default is list(plotFig=TRUE, sumOverStrains=FALSE, resourceLegendPosition="topleft", microbeLegendPosition="topleft", saveFig=FALSE, figType='eps', figName='microPopFig', yLabel='Concentration (g/L)', xLabel='Time').
To turn off plot generation set plotFig=FALSE. If there are multiple strains these are all plotted if sumOverStrains=FALSE, otherwise they will be summed over each group. To save plot, saveFig=TRUE, figType (format) can be 'eps','png', 'pdf' or 'tiff' and is specified in figType (string), the name is figName (string) to which the string 'Microbes' or 'Resources' will be added for the respective plots.

odeOptions

List containing instructions for the ODE solver ('deSolve'). Default: list('atol'=1e-6,'rtol'=1e-6,'method'='lsoda'). See ?ode for more details.

strainOptions

List containing instructions for specifying strain parameters. Default: list(randomParams=c('halfSat', 'yield', 'maxGrowthRate', 'pHtrait'), seed=1, distribution='uniform', percentTraitRange=0, maxPHshift=0, applyTradeOffs=FALSE, tradeOffParams=NULL, paramsSpecified=FALSE, paramDataName=NULL).

• randomParams (vector) specifying which parameters need to be stochastically generated.

• seed (number) seed for random number generator.

• distribution (string) - either 'uniform' or 'normal' specifying the shape of the distribution from which to draw the random strain parameters.

• percentTraitRange (single number or named vector of numbers) this is the percentage either side of the group parameter value which the strain parameter may range e.g. if percentTraitRange=10 then range is 0.9x to 1.1x for group mean x. This can be specified for each microbial data file in microbeNames using a named vector, however, if only one number is given it is assumed to apply to all microbes.

• maxPHshift (number) pH units to range over (either one value which is applied to all microbe groups or a named vector with a value for each group and microbeNames for its names).

• applyTradeOffs (logical) to trade off ‘good’ and ‘bad’ parameter values.

• tradeOffParams (vector of two strings) - parameters to trade off against each other. Note that pHtrait can not be traded off as whether this trait is good or bad depends on the environmental pH.

• paramsSpecified (logical) TRUE if strain parameters are read in from a file (whose name is specified in paramDataName). The file must have colnames c(strainName, paramName, paramVal, paramUnit, resource,path) and where strainName is in format 'groupName.i' where i is the strain number.

checkingOptions

(List) Default is list(checkMassConv=FALSE, balanceTol=1e-2, reBalanceStoichiom=FALSE, stoiTol=0.1, checkForNegs=TRUE, negTol=-1e-2).

• checkMassConv=TRUE checks for mass conservation in the ODE solver with a tolerance of 'balanceTol' (default is FALSE).

• reBalanceStoichiom will check the mass balance of the stoichiometries on every metabolic path and rebalance if these are not conserving mass within a tolerance of stoiTol (a warning message will be issued). Rebalancing will only affect the final solution if the pathway contains only essential resources (Rtype 'Se') and microbial biomass is a product (Rtype 'Pb').

• checkForNegs If TRUE the function checkSolution is called and the solution for each variable, x, is checked for negative values that are greater in magnitude than negTol*max(x). If negative values occur then the solution is incorect and either the problem is incorrectly specified or the tolerances in the ODE solver need to be smaller.

microbeMolarMass

Scalar. Mass of 1 mole of microbes - default is 113g/mol (Batstone et al., 2002)

bacCutOff

Scalar. Amount of bacteria below which the bacteria are considered to have left the system and can't grow, default =1e-14. If this is set to zero then bacteria will always be able to grow again as zero is never reached.

networkAnalysis

Logical. If you want to use the network analysis functions on your model results set as TRUE (default is FALSE)

myPars

List containing extra parameter values - used if gutModel is TRUE i.e. with microPopGut package

...

Add your own input arguments

Value

The output is a list containing a matrix called 'solution' where rows are points in time and the columns are the state variables, and another list called parms which contains all the information needed to run the model. Within parms there are a number of other lists (e.g. Pmats for parameter values and Smats for system settings etc - try names(out$parms)).

Examples

#simplest example - define one microbial group (Archea) with 4 resources and
#simulate growth over 50 days
#make microbial group data frame:
MFG=matrix(NA,ncol=4,nrow=6,dimnames=list(c('Rtype','halfSat','yield',
'maxGrowthRate','stoichiom','keyResource'),c('H2','CO2','CH4','H2O')))
MFG['Rtype',]=c('Se','Se','P','P')
MFG['halfSat',c('H2','CO2')]=1e-6
MFG['yield','H2']=0.2
MFG['maxGrowthRate','H2']=2
MFG['keyResource',1]='H2'
MFG['stoichiom',]=c(4,1,1,2)
Archea=data.frame(MFG,stringsAsFactors=FALSE)

#make resourceSysInfo data frame
Rmat=matrix(NA,ncol=4,nrow=4,dimnames=list(c('startValue','inflowRate',
'washOut','molarMass'),c('H2','CO2','CH4','H2O')))
Rmat['startValue',]=c(1,1,0,0)
Rmat['inflowRate',]=c(1,5,0,0)
Rmat['washOut',]=c(0.1,0.1,0.1,0.1)
Rmat['molarMass',]=c(2,44,16,18)

#make microbeSysInfo data frame
Mmat=matrix(NA,ncol=1,nrow=3,dimnames=list(c('startValue','inflowRate',
'washOut'),c('Archea')))
Mmat['startValue',]=1
Mmat['inflowRate',]=0
Mmat['washOut',]=0.1

out=microPopModel(
    microbeNames='Archea',
    times=seq(0,50,0.1),
    resourceSysInfo=data.frame(Rmat,stringsAsFactors=FALSE),
    microbeSysInfo=data.frame(Mmat,stringsAsFactors=FALSE)
)