Parse Pmetrics Simulator Output

Parses the output of the Pmetrics simulator. This is largely superseded as it is automatically called by either of the simulation methods: PM_result$sim() or PM_sim$new(). There is rarely a need any longer to call this function directly.

Usage

SIMparse(file, include, exclude, combine = F, quiet = F, parallel)

Arguments

file

An output file or files of the simulator in the current working directory, or the full pathname to the file. To load and combine multiple outputs, specify files separated by commas or using wild cards. See details.

include

A vector of files to include in the parsing. For example, if you used a wild card in the file argument, such as “simout?.txt”, which returned four files: simout1.txt, simout2.txt, simout3.txt and simout4.txt, and you wished to only parse the first and fourth file, specify include=c(1,4).

exclude

See the discussion for include, but this will exclude specified files.

combine

Boolean parameter, default False, which specifies whether you wish to combine the parsed files into a single PMsim object. This can be useful for making visual predictive checks, for example. If combine=F, and multiple files are parsed, then the return object will be a list of PMsim objects, which can be plotted or otherwise accessed using standard list referencing, e.g. simlist[[1]], simlist[[2]], etc.

quiet

Suppress messages

parallel

Runs in parallel mode. Defaults to true if multiple files are to be parsed, otherwise false. Can be overridden by specifying TRUE or FALSE.

Value

If one file is parsed or multiple files are parsed and combined, the return will be a list with five items, of class PMsim. If multiple files are parsed and not combined, then the return will be a list of PMsim objects.

obs

An data frame of simulated observations with 4 columns: id, time, out, outeq. id is the number of the simulated subject, which will have a unique ending appended if simulations are combined, such that id will become x.y with x being the simulated profile number and y being the simulation template number. time is the time of the simulated output, out of output equation number outeq.

amt

An data frame of simulated amounts with 4 columns: id, time, out, comp. id is the number of the simulated subject, which will have a unique ending appended if simulations are combined, such that id will become x.y with x being the simulated profile number and y being the simulation template number. time is the time of the simulated amount, out in compartment number comp.

parValues

A datframe of the simulated parameter values, combined across files as necessary

totalSets

The total number of parmeter sets simulated, which may be greater than the number of rows in parValues if some sets were discarded for being outside specified limits. For more than one file parsed, this will the total number in all files.

totalMeans

The means of each simulated parameter based on all profiles in a given file (even those discarded for exceeding limits). For more than one file parsed, this will be the weighted averages for all simulations.

totalCov

The covariances of the simulated parameter sets based on all profiles in a given file (even those discarded for exceeding limits). For more than one file parsed, this will be the weighted averages for all simulations.

A plot method exists in plot.PMsim for PMsim objects.

Details

For file specification “?” will be matched by just a single numeral or character; “*” will be matched by any number of consecutive alphanumeric characters. Examples include file='simout1.txt,simout2.txt,simout3.txt', file='simout?.txt' and file='sim*.txt'.All three will find the files simout1.txt, simout2.txt, and simout3.txt in the working directory. The second example would also find simout4.txt, etc. The third example would also find sim_1.txt if that existed. Note that to combine simulator output files, the numbers of simulated profiles may differ. The number of outputs and times of observations also may differ, although combining these may lead to strange plots since not all profiles have the same observations. For parallel execution, the function requires packages 'doParallel' and 'foreach'. If not installed, it will try to install, failing that it will run in serial mode.

See also

PM_result, PM_sim, SIMrun

Author

Michael Neely