Changelog
Source:NEWS.md
NMsim 0.1.4
CRAN release: 2024-11-02
New features
sampleParsSimpar()
is a new function that automates sampling of parameter values from an estimated variance-variance matrix in a successful$COVARIANCE
step using thesimpar
R package from Metrum Research Group.simpar
is currently not on CRAN, so the user must install it from MPN or github to make use ofsampleParsSimpar()
. The sampled parameter values can be fed directly toNMsim
using theNMsim_VarCov
method making it very easy to simulate with parameter uncertainty based onsimpar
. I want to thank Sanaya Shroff for her outstanding work on this functionality and for her exciting work summarizing the available methods for simulation with parameter uncertainty which she will be sharing at ACoP 2024. Also a big thanks to Eric Anderson for helping out with adjusting the github workflows to pullsimpar
from MPN.expandCovs()
is a new function that puts together data sets for univariately varying covariates while keeping other at reference values. The function can derive both reference values and covariate values to simulate at by using i.e.median()
andquantile()
.-
- Results are now equipped with three columns distinguishing simulated models. This separation of information makes it easier to summarize simulation results within/across models and/or within/across simulation of models.
-
model
: The run name derived fromfile.mod
. -
name.sim
: The same as provided in thename.sim
argument. -
model.sim
The name of the generated model. In the simple case, this ismodel
andname.sim
combined. But in many cases, multiple models are being generated for each simulated control stream.
-
- No longer requires a
.ext
file if updating parameter values using PSN’supdate_inits
. It is still recommended to keep the.ext
file since it provides higher accuracy than the.lst
file.
- Results are now equipped with three columns distinguishing simulated models. This separation of information makes it easier to summarize simulation results within/across models and/or within/across simulation of models.
-
When submitting all updated models,
NMexec()
will now by default try to detect if a model is already running before submitting it.Provides a summary of models to be submitted before starting to do so.
-
ADDL
andII
are now also separate arguments providing a simpler interface than theaddl
argument. Theaddl
argument provides the advantage of being able to specify the two columns together in onedata.frame
, possibly including covariates.add.lastonly
is a new argument. IfTRUE
(default) andADDL
andII
are of length 1, they are only applied to the last event in a dosing regimen.col.id
argument to specify name of subject id column or to omit altogether usingcol.id=NA
.Now checking that
TIME
is covering the length of all other arguments. In contrast to other arguments, it does not make much sense to try to extrapolate theTIME
argument.
addEVID2()
now has two arguments,TIME
andTAPD
which allow for specification of time since first dose and time after each dose at which to insert simulation records. The two can even be combined.TIME
replaces the now deprecatedtime.sim
argument, andTAPD
is new.
Bugfixes
A bug most likely affecting most Windows users for execution of Nonmem has been fixed. If on Windows, you should upgrade to NMsim 0.1.4. Thank you to Boris Grinshpun for reporting this!
When using
method.execute="nmsim"
there was an issue with parallellization. This was not a major problem in most simulation applications, but it should now be fixed.-
- When not providing a simulation data set - typically a simulation for a VPC -
NMsim()
would fail with messages like
- When not providing a simulation data set - typically a simulation for a VPC -
Error in `:=`((col.sim), ..name.sim) :
Check that is.data.table(DT) == TRUE. Otherwise, := and `:=`(...) are defined for use in j, once only and in particular ways. See help(":=").
The issue has been fixed. If using NMsim 0.1.3 or earlier, the workaround is to do NMdataConf(as.fun="data.table")
. Then after having the simulation results as a data.table, convert it with as.data.frame()
or as preferred.
Notice, NMdataConf()
affects the succeeding NMsim()
calls but also other NMdata and NMsim function calls. When the VPC simulation has run, you may not want to continue recieving data.tables, you should reset the default value for as.fun: NMdataConf(as.fun=NULL)
which will turn it back to returning data.frames by default. If you prefer tibbles, you can do NMdataConf(as.fun=tibble::as_tibble)
. Generally, if you prefer to work with something that is not data.frames (data.table and tibble the most common alternatives), it is recommended to use NMdataConf()
to customize your default.
-
NMexec()
-
NMexec
would fail running control streams named starting in numerals (like1.mod
) whensge=TRUE
. This is due to the waysge
job names are generated byNMexec()
. Fixed by prepending “NMsim_” in these cases.
-
-
NMcreateDoses
- Would in some cases create too many replicates if there were covariates on multiple arguments. Fixed.
NMsim 0.1.3
CRAN release: 2024-08-26
New features
-
New simulation method
NMsim_NWPRI()
to simulate with parameter uncertainty. This automates simulation with parameter uncertainty using Nonmem’sNWPRI
subroutine for models with a successful covariance step. For now this method only works forTHETA
since we have found that the parameter distributions sampled forOMEGA
andSIGMA
do not always match the model estimates and therefore cannot be trusted. To ensure that onlyTHETA
are sampled and simulated, this method should only be run using thetypical=TRUE
argument. This method is much faster than the existing methods in NMsim for simulation with parameter uncertainty (NMsim_VarCov()
). This method depends onNMdata
version 0.1.7 or greater. Big thanks to Brian Reilly for his excellent work on this important contribution.The
add()
function to be used inNMsim()
’smodify.model
argument now supports prepending and appending of text lines to control stream sections. The default is still to append andadd("text",.pos="top")
will now prepend “text”.
-
A “cleaning” feature has been added to
NMexec()
, removing some of the temporary files generated by Nonmem after ended execution. The interface is inspired by PSN’sclean
argument supporting values 0 (no cleaning), 1-4 (quite some cleaning - so far no difference betwen these values), and 5 for complete deletion of the temporary directory. When usingmethod.execute="PSN"
NMsim calls PSN’s execute passing on theclean
value.Default number of cores to be used by
NMexec()
can be controlled usingNMdataConf(nc=N)
whereN
is the desired default. Notice,NMsim()
will not use this default. This is because parallellization is not as commonly used in simulation as in estimation.A useful backup feature has been added. Before execution, any existing results files related to a model are by default moved to a backup folder. The backup files are not
NMsimTestConf()
- Function to summarize and test configuration. This is used internally and provides important debugging information.readParsWide()
- A function to read wide-format parameter tables - is now exported. This is useful when simulating with parameter values that have been sampled outside Nonmem, e.g. using thesimpar
package.
Bugfixes
NMexec()
would fail on linux when run on models with multiple$TABLE
statements. Fixed.NMsim
’s internal method to update parameter initial values had an issue running on models with$OMEGA
block structures. Fixed.NMreadSim()
would fail if working directory had been changed. Fixed.
NMsim 0.1.2
CRAN release: 2024-07-15
No changes since 0.1.1 except for disabling a test that was failing on some systems due to technical reasons.
NMsim 0.1.1
CRAN release: 2024-07-03
While no critical and generally only few bugs have been found in NMsim 0.1.0, NMsim 0.2.0 includes several improvements and upgrades. The interface feels smoother too. I want to thank Ron Keizer for feedback and advice.
New features
NMsim()
has a much reduced and improved messaging to the user. If more than one model or data set is supplied or generated, progress trackers will be shown while starting Nonmem, while waiting for Nonmem to finish, and while collecting the simulation results.The messages include information about where intermediate files and final results files are stored.
NMexec()
has improved support for estimation.method.execute="nmsim"
andmethod.execute="psn"
both work on linux and windows, even though less thoroughly tested on windows. Thank you to Boris Grinshpun for testing.Names of files containing final results from
NMsim()
have been renamed to be more intuitive. The previous_paths.rds
will now be called_MetaData.rds
. The results, once read and compressed, will be in a file called_ResultsData.fst
. Notice, both these files are required to fully recover simulation results. Thanks to Brian Reilly for discussions on this and many other design aspects.It is now possible to provide specific parameters (
THETA
,OMEGA
andSIGMA
) for Nonmem simulation.NMsim()
table for simulations. See argumentfile.ext
andNMsim_VarCov
’s argumentext
.New arguments to control seeds.
NMsim
can either use R’sset.seed
before generating the seeds for Nonmem. Detailed control of the seeds, including how many to include and the distribution of the random sources in Nonmem, can be controlled using theseed.nm
argument. This way, the user can add random processes to the estimated control stream. The actual Nonmem seed values can also be provided.method.sim=NMsim_typical()
has been replaced by argumenttypical=TRUE
. This means typical subject simulations can now be combined with other simulations methods likeNMsim_VarCov
.NMsim()
now adds a column calledsim
which carries the name of the simulation defined by thename.sim
argument.Several checks for existence and consistency of files are implemented.
The native Nonmem execution method now also works for estimation.
pnm
files are now saved with the model for transparency.
Bugfixes
Running
rbind
on results fromNMsim
would throw errors. Thanks to Simone Cassani for reporting this. Fixed.Using other file name extensions than
.mod
on input control streams in combination withNMdataConf(file.mod)
would make NMsim fail. Thanks to Brian Reilly for reporting. Fixed.
Other changes
NMsim_known()
renamed toNMsim_EBE()
.Generated control streams have been stripped off of the “NMsim_” prefix. These files are located in
NMsim
generated folders so the prefix was uninformative.In case of multi-threaded (cluster) execution and something went wrong
NMexec()
used to write some output files from Nonmem in the current working directory. All these are now being written to the model execution directory for clarity and tidyness.
NMsim 0.1.0
CRAN release: 2024-02-22
For the first time NMsim works on Windows. There may still be some limitations but initial testing looks very promising. Make sure to set path.nonmem
. See the configuration vignette on the website: NMsim-config.html
0.1.0 is also an important upgrade that solidifies the way NMsim reads results from simulations. In addition to important bug fixes, it allows for NMsim to wait on Nonmem to complete simulations - even when they are run on a cluster. This means even large simulations with NMsim can be integrated in scripts.
New features
Works on Windows - at least most features do.
NMsim()
andNMreadSim()
now havewait
arguments which controls if they will wait for Nonmem to finish simulating. This will also work if jobs were sent to the cluster.NMsim()
respects thereuse.results
argument. IfTRUE
it will use results file on the file system. This can be used in stead of puttingNMsim()
calls inside an if-statement to disable the simulation but read results on file.NMsim()
looks for a couple of features of the provided control streams that are known to be able to cause issues. Warnings will be issued if these are found.addEVID2
has a new argument,EVID
to specify what value theEVID
column should have. It can be useful sometimes to useEVID=0
for simulation records.
Bugfixes
- In some cases
NMreadSim()
would not get the path right to the simulation results leading to failures in reading simulation results. Fixed.
NMsim 0.0.10
CRAN release: 2024-02-08
NMsim 0.0.9 had an unfortunate bug in NMreadSim()
which has been fixed. That bugfix is difference between 0.0.9 and 0.0.10.
NMsim 0.0.9
CRAN release: 2024-02-07
NMsim 0.0.9 is almost identical to 0.0.8 but ensures compatibility with older R versions.
NMsim 0.0.8
CRAN release: 2024-02-07
New features
NMsim
0.0.1 would generate anrds
file with paths to simulation files and results for each model+data set simulated. This has been changed to now only generate one table per model. This makes it simpler to read simulation results in some cases.NMreadSim
should now be the best and only way for the user to readNMsim
simulation results. It interpretsrds
files (which are the ones intended for reading),fst
files, tables ofNMsim
runs, andNMsim
results. This makes it less confusing what can be processed byNMreadSim
and also it sometimes easier to generalize code reading simulation results. Also,NMsim
now always reads results usingNMreadSim
. This has the advantage that an fst file will always be produced ifNMsim
waits to read the results.NMreadSim
has a new argument,check.time
by default disabling checking whether a collectedfst
file is newer than the results files generated byNMsim
. Normally, it’s a good thing to check this but some ways of sharing file files may not retain file modification times needed to check for this.NMsim
will delete thefst
files if it finds any so normally it should not be a problem to skip this check.modify.model
is the argument to use to modify the control stream afterNMsim
is done preparing the simulation. A couple of helper functions are available making it really easy to add contents (very commonly used) or modify contents.NMsim
now tries to reuse stored results ifreuse.results=TRUE
. It does so in a simple way - if they exist, they will be attempted read - so be careful to rerun simulations without this option if you change any arguments.NMsim
will by default add aDV
column withNA
values ifDV
is not in input data. Nonmem most often needs that column, and it is uninformative for simulations. Disable this feature by usingauto.dv=FALSE
.The
transform
option has been integrated into the table of simulations created byNMsim()
. This means even if the results are not read byNMsim
(because the simulation is not executed or it is submitted to a cluster), the transformation will still be applied byNMreadSim()
later.NMsim()'s
dir.sims
anddir.res
arguments can be controlled usingNMdata::NMdataConf()
. Often these two arguments are used all the time, so it’s convenient to be able to configure those once and for all in a script.
Bugfixes
NMreadSim
was only able to read results if the current working directory was the same as whenNMsim
was executed. Now fixed.In some cases
NMsim
would fail on models with multiple output tables when thetable.vars
argument was not used. Fixed.NMsim
’ssim.dir.from.scratch
argument was not respected due to a simple bug, leading todir.sims
growing each time a simulation was rerun.In case simulation data is a list of data sets
NMsim
would not order columns whenorder.columns
wasTRUE
. Now fixed.In case of lists of data sets, and the list element (data set) names included spaces,
NMsim()
would throw and error. Spaces in data set names are now replaced with under scores (“_“) to avoid that. It will often happen when data sets are split into lists usingdata.table::split.data.table()
- which is an excellent way to do this, by the way.Function
simPopEtas()
was not exported, so only available asNMsim:::simPopEtas()
. Fixed.
NMsim 0.0.7
CRAN release: 2024-01-08
New features
Function
simPopEtas()
to generate a population from a model. The population can be saved as aphi
file to be reused in subsequent simulations. The function is by mistake not exported in 0.0.7 so for now you must useNMsim:::simPopEtas()
to use it.Function
NMreadSim()
provides a very simple interface to reading simulation results. Especailly in cases where the simulation is being parallelized or otherwise spawns multiple Nonmem jobs, this is a useful feature.A list of simulation data sets will now be simulated with separate Nonmem runs. This is an efficient way to parellelize large simulation runs.
NMsim 0.0.6
CRAN release: 2023-11-28
New features
- Support for parallelization of simulations added when using PSN. It used to be possible to run multiple simulations simultaneously in separate threads. Now single simulation runs can be parallelized on
sge
type clusters (usingqsub
). See argumentssge
andnc
.
Bugfixes
- A simple mistake would create problems in
genPhiFile()
when having more than 10 ETAs in a model. Now fixed.
NMsim 0.0.5
CRAN release: 2023-11-11
New features
Full support for models estimated with SAEM. Especially, simulation of “known” subjects, i.e. re-using emperical Bayes estimates, is slightly different with these models.
Experimental support for windows with PsN.
dir.psn
argument has to point to a directory where executablesexecute
andupdate_inits
are found. Thanks to Sjoerd Koopman for debugging and testing this. Hopefully in future versions,PsN
will not be needed on Windows (like it is not needed on Linux).The simulation method called NMsim_known now accepts other
.phi
files to use than the .phi file generated by the estimation run. This is useful if one wants to reuse subjects generated in a previous simulation.