NEWS.md
New model syntax: THETA(n) is interpreted as THETAn in the model code; THETA is now a reserved word (#837, #891, #892).
New functions collapse_omega(), collapse_sigma() and collapse_matrix() added which help to reshape OMEGA and SIGMA matrix objects with multiple blocks (#897, #900).
New plugin nm-vars which implements NONMEM-like syntax for referring to compartments, differential equations, bioavailability factor, infusion duration and rate, and lag time (#904, #891).
New plugin autodec which will find user-defined variables in the model code and automatically declare them as type double (#905, #893).
Use ii as spacer for setting the between-dose interval when putting event objects in a sequence (c.f. wait) (#906, #901).
Start deprecatingsimeta(n) and simeps(n), calls to simeta() or simeps() with an integer argument thus limiting the update to just a single ETA(n) or EPS(n); use in model code will generate warning when loading the model that contains the n integer value (#908, #909).
In pk2iv, change scaling volume for CENT from V2 (incorrect) to V1 (#831, #832, #833)
Fix bug collating multiple $OMEGA or $SIGMA matrices when parsing a model (#863)
Refactor how debugging information is processed when using the recover argument to mread() (#853)
Fix typo in documentation for as_cmat(); the off-diagonals are assumed to contain correlations (#856)
Wrote a as.data.frame.matrix() function in Rcpp; all simulation results return from the C++ simulation code as a data frame (#857)
Fix bug where dynamic capture (via mread()) was not allowed for variables declared in $GLOBAL (#868)
mrgsim() will now periodically check for user interrupt signal so that long-running simulations can be stopped using Esc and / or Control-C; the check interval can be modified through the interrupt argument to mrgsim(), but for most applications, this shouldn’t need to be changed (#823)mrgsim() will issue a warning if duplicate columns are found in simulated output and rename duplicates using make.names(); thanks @FelicienLL for the report (#827, #828)OFF when they have active infusions running; this was previously an error (#822)root.xml or root.ext) are now saved in the model object when nonmem results are imported via $NMEXT or $NMXML; paths are accessible by coercing the model object with as.list() and looking at the nm_import item (#802)root argument to $NMEXT and $NMXML so that the nonmem output files are located relative to the working directory (default, previous behavior) or the directory where the cppfile is stored; cppfile will eventually replace working as the default (#803)$PRED now respect the obsonly option (#811)simeta() and simeps() now accept an (optional) integer argument to limit re-simulation to single ETA or EPS values (#789)as.list(mod) output now includes a data frame of C++ variables and pre-processor definitions in the cpp_variables slot. (#780)$PARAM, $THETA, $CMT, $INIT, $OMEGA and $SIGMA blocks all include the directives @object and @as_object so that block contents can be specified programmatically. @object names an object that was coded into $ENV and @as_object indicates that the block contains code to realize the object. See ?BLOCK_PARSE help topic for more information on how this all works. (#783)$NMEXT now lets the user select between multiple tables for scraping parameter estimates. (#782)$ERROR as an alias for $TABLE in the model file #710rtol and atol rather than ss_rtol and ss_atol #703loadso issues a proper error when the model dll doesn’t exist #724addl or ss are negative #733tad plugin to calculate time after dose in a specific compartment #702carry_out to respect default nocb behavior #759; see also #744capture argument to mread to add to $CAPTURE when compiling the model #704recover mechanism to join items in input data sets to the output #646ss_rtol and ss_atol) to control advance to steady state #652realize_addl when addl is zero by ii is not #653tname to add custom names to imported THETAs #687run.ext file #509select_sims method for selecting columns in mrgsims object #585CXX_FLAGS in $ENV block #603N_CMT plugin so that the number (index) of every compartment is available by name (e.g. N_CENT for the number index of the central compartment) #606blocks() failed when the model was defined in Rmd file #608within method for mrgmod #616$ operator for mrgmod #620c("mrgsims", "character"); pass in a character vector of outputs to plot #630mrgsolve:::house() is now an exported function #625qsim and all associated functionsqsim as a simpler, quicker simulation routine #490mrgsim() and variants) recognizes evid 4 in addition to evid 1 #502$NMXML fails when nm namespace not found in xml file #510ev constructor are now evaluated; for example, ev(amt = 100, rate = amt/2) #512$ and [[ operators for event objects #513mrgsim_e and mrgsim_ei will try to accept data frame and validated data setsoutvars argument to update method; this will replace Req
ss_n and ss_fixed to control advance to steady state; a warning will be issued when ss_fixed is FALSE and the system doesn’t reach steady state within ss_n iterations #533xpath is added to nmxml() to handle cases where the nm namespace is not found in the xml file #510istate #457ss=1 in a dosing record with bioavailability is zero #497rate/tinf, addl/total, addl/until #513tinf is used to create event object, that item is retained and used to set the infusion rate (along with dose) until it is removed; it is an error to try to set rate when tinf is in the event object #513expand_observations #563expand_observations to allow control record sort order #565DLSODA code to avoid CRAN LTO warningmrgsolve_q to call the standard mrgsolve simulation rather than the streamlined function; a decision will have to be made about whether or not the streamlined function will be retainedvalid_data_set now retain the matrix attribute #448simcall to 0 in mrgsim_q@as_object option to the following blocks: PARAM, INIT, CMT, OMEGA, SIGMA; experimentalODE blocksmtime function to self object for simpler mtime implementation@param block option for ODE blocks; use comma-separated name=value pairs to add to the parameter list from within ODElogy and logbr arguments to plot.mrgsims so results y-axis outputs can easily be plotted on log scalenumerics_only function to drop non-numeric columns from the input data set after optionally converting logical columns to integerev_rx function to write dosing interventions in notation similar to a prescription ‘sig’$PRED block for models that don’t utilize any compartmentspred1 to the internal model library (modlib())mrgsim_q function for simulation from a model object with quicker turnaround timemread will take soloc and project arguments from options() as mrgsolve.soloc and mrgsolve.project, respectivelyoutput argument to mrgsim so that e.g. data.frame can be returned, without creating the usual mrgsims objectsoloc argument of mread (or mcode or cache versions of both) will be created if it doesn’t existpk2iv model as convenience optiontinf argument to ev() constructor functiontime/TIME is no longer required in a data set when $PRED is in usecmt/CMT is no longer required in a data set; a default value of 0 will be assigned in case it is missing and an error will continue to be generated when dosing into an invalid compartment (0 is always an invalid index for dosing compartment)NA) are detected in an input data set with the following names: ID, time/TIME, or any column that shares a name with an item in the parameter listindex argument was added to the $NMXML block to allow results selection when multiple estimation blocks were used. The new default is to use the last result.modlib is now able to function as a wrapper to mread for models in the model library so that, for example, modlib("pk1") is equivalent to mread("pk1", modlib()).s and replaced with s_; this was not a problem created by mrgsolve but rather by ggplot2, which calls mgcv::s via geom_smooth under certain circumstancesas.list.mrgmod so that the names match the names that you would pass to update.mrgmod; also added some items so that all updatable slots in the model object are exported by calling as.list #354as.list.mrgmod output under the names omat and smat, respectivelydplyr::filter_ for filter_.ev
mutate_sims and filter_sims that work on mrgsims (output) objects, modifying the data slot and returning a modified mrgsims object rather than data.frame
plot_sims function that takes a data frame of simulated output and generates a plot using the mrgsims methodid argument to ID in ev_rep and ev_seq; a warning is issued if id is useddata_qsim for creating input data sets to use with qsim
read_nmext to read in nonmem model output from the .ext filemread("mymodel.txt") will read from the file mymodel.txt if it exists. However, the default behavior remains unchanged so that mread("mymodel") will expect to find the model in the file mymodel.cpp.project path formulations #315The realize_addl function was re-factored to better account for time-varying data items; more option are provided for seeing where rows were inserted into the data set and whether to make assumptions about other data in those rows or not
mrgsolve no longer utilizes any functions from the XML package. All previous functionality that depended on XML now depends on xml2. As such, xml2 is listed under the Suggests dependency.
When using $NMXML, the $OMEGA and $SIGMA matrices are now loaded by default; see new default arguments to mrgsolve:::nmxml
Bioavailability specified in $MAIN is accounted for when simulating with qsim; there is still no bioavailability adjustment for infusions or lag times adjustments to doses
Added capability to rename data items in $CAPTURE; also, names are partially sanitized, removing parens and brackets.
For example $CAPTURE WT = WGT ETA(1) TVCL = THETA1
Added qsim_df function, returning data frame rather than matrix
Added as.list method for mrgsims objects
Added deep argument for as.list method for mrgmod object; it was taking a lot of time to return the function set, so now you only get it if deep = TRUE
Added mrgsim variant functions with explicit input requirements written into the function name. For example, call mrgsim_e to simulate from an event object, mrgsim_d to simulate from a data frame. All of these functions are called by mrgsim.
Added method so that event objects can be passed to data_set; also, coercing event objects to data_set when passed in as data
Added all.equal.mrgmod function to compare two model objects. The function returns logical (only)
Added env_get_env that always just returns the model environment; it has identical result as env_get(mod, tolist = FALSE)
Change mread_cache and mcode_cache so that the cache is invalidated when preclean argument is TRUE
mrgsolve_example and mrgsolve_template; these had been deprecated previously with warning; use modlib() models instead_env when mrgx plugin is invokedAdded file argument to mread to allow coding model specification files with any extension. The current behavior continues to be assuming that the model is in a .cpp file, but using the file argument allows any file name for model specification.
Added nocb argument to mrgsim. If nobc is TRUE (default), mrgsim continues to use next observation carried forward to advance the system when there are time-varying parameters (including covariates). If nocb is FALSE, mrgsim will use last observation carried forward (locf) to advance the system when there are time-varying parameters.
self object was not correctly updated for the first record for an individual (#273)ev_assign is changed so that the unique values of evgroup are sorted prior to making event assignments. Details about the new behavior are now included in the R help topic.addl. The previous behavior had bioavailability parameter locked at the value at the time the initiating dose was implementedRcpp >= 0.12.12 and dplyr >= 0.7.1
ss=2 are recognized, allowing combining of steady-state dosing regimens under linear kinetics (e.g. 10 mg QAM and 20 mg QPM) (#221)inventory) that reconciles model parameters with names in an object (e.g. a simulation data set) verify that required parameters can be found in the data object.tad) in the simulated output. Use mrgsim(tad=TRUE).$PLUGIN mrgx, including mrgx::get<T> for getting objects out of $ENV or a package namespace and mrgx::mt_fun() that is just a function that you can assign when declaring Rcpp::Function.object argument to idata_set and data_set to get a data.frame (or function to call that returns data.frame) out of $ENV to use for simulation.cmt argument to $PKMODEL. When cmt is set to a character vector or a comma-separated string, $PKMODEL infers the number of compartments and declares them in the model. This means a separate $CMT block is not required when using $PKMODEL.cols argument to as_bmat and as_dmat so that a character vector of names can be specified (rather than regular expression) to select data for creating matrix.preclean argument now causes unlink to be called on the model build directory.$ENV: ls_env, get_env, re_eval_env, update_env.table() macro in $TABLE is now deprecated (https://github.com/metrumresearchgroup/mrgsolve/pull/129). To get derived values into the simulated output, users should assign to type double and list that variable name in $CAPTURE. See also the capture typedef introduced below.mrgx plugin was completely removed.param method with signature missing will check names of input parameters against names of existing parameters. An error is generated if a user attempts to update a parameter that doesn’t exist. Note that this does not apply for the param method with signature list (#144).@ macros for indicating block options in model specification file.qsim function for quick(er) simulation runs with just one parameter set.recmatrix that creates matrix simulation template for qsim.mrgsolve:::render to create a document with overview of model contents. Methods for both mrgmod objects and character strings pointing to a model file.mrgsolve:::details to extract model annotation.capture typedef in the model specification file. Variables that are type capture are doubles and are automatically appended to $CAPTURE.capture typedef is not allowed in $ODE and probably should be reserved for $TABLE.simeta is available in $MAIN and simeps is available in $TABLE by default, no $PLUGIN is required.R objects in the model via $ENV (#158).assign_ev function to help build simulation data sets from event objects (https://github.com/metrumresearchgroup/mrgsolve/pull/164).as_data_frame method from the tibble package (#166).$ operator for mrgmod objects to return the value of a parameter.mread_cache and mcode_cache functions to build and cache a model (#143).PKMODEL. The volumes for two-compartment model with no depot should be V1/V2.knobs where output column names are malformed when a user $CAPTUREs a parameter that is also being tweaked as a knob.double/int/bool in $MAIN, $ODE, $TABLE are kept in unnamed namespace and are local to the file..R files.mrgsolve:::details returns a data frame of information regardless of whether the model was annotated or not (#165).mrgsolve::details has additional arguments to help control output.pkevent class; all records are datarecord.$PARAM, $FIXED, $THETA, $CMT, $INIT, and $VCMT. (#107)mrgsolve:::house() model re-coded as an annotated model.$ENV to allow users to create R objects that can be used at certain points when parsing the model. (#115)>> signifier to code blocks that allow options; >> at the beginning of the line indicates that the name=value statements that follow are to be parsed as block options.object argument for the following blocks: $PARAM, $OMEGA, $SIGMA, $FIXED, $CMT. When object is set to a character string naming an object in $ENV, that object will be used to form the output from the block.valid.numericlist wasn’t returning FALSE for improperly-formed objects.modmrg package was discontinued. All of the pre-coded models are now available in mrgsolve. Simply call mread with the model stem (e.g. pk1cmt, irm3, etc …) and call modlib() as the project argument.mod <- mread("emax", modlib()) will compile the emax model and return the model object.Windows systems failed when certain symbol names were used in the model (#97). In this release, a dllname-win.def file is created in soloc to export only the functions that mrgsolve needs to use. This is only relevant to Windows platform.project argument to mread: if newline(s) are found, an error is generated and the user is prompted to use mcode instead.cwd to soloc is not required to build the model. This was only required on Windows systems where there was a space in the file name. Correctly rendering the path for the build directory now.as_data_set to convert one or more event objects into a data frame that can be passed to data_set. Does something similar to expand.ev, but more control.time, amt, rate, evid, ii, addl ,ss, cmt) either lower case or upper case names are recognized. The determination is made on the time / TIME column (always required when using a data set). If time mrgsolve will continue looking for lower case names; if TIME it will look for upper case names. A warning is issued in case both upper and lower case names are included.$PLUGIN to let users extend their model specification file. Valid plugins include simeta, Rcpp, RcppArmadillo, and BH. When a plugin is used, mrgsolve will link back the the appropriate package and possibly include appropriate header files when compiling the model. For example, simeta will link back to mrgsolve and RcppArmadillo and allow the modeler to simulate a new set of ETAs. Use Rcpp plugin to simulate random variates from common distributions in R(e.g. rnorm, rexp etc … ).$PKMODEL with ncmt=2 and depot=FALSE, the default PK parameters are CL, V1 (central volume), Q, V2 (peripheral volume).V2 (central) and V3 (peripheral).$CAPTURE now saves output items to slots in std::vector<double>, rather than std::map<std::string,double>. We’ve known for a while that the std::map wasn’t very efficient especially with large simulations.$TABLE are still saved into std::map with table() macro. The plan going forward is to eliminate that table map and force output variables into $CAPTURE.dplyr, now requiring dplyr >= 0.5.0 (#69)data slot in mrgsims objects is now data.frame
knobs function and plot method has been re-written. Overall behavior for most applications should be the same.C++ symbols for model functions are now stored in the model object (funs slot)mrgsolve:::funset(mod)
funs can be found with is.loaded
soloc directory (by default tempdir()), but mrgsolve will create a subdirectory structure to organize compilation artifacts. The outer directory is keyed based on the current mrgsolve version number and the computer platform. Inner directories are based on the model name (model(mod)).model name and the shared object is created based on that name. If the compilation is successful, the shared object (.so on mac/unix, .dll on Windows) is copied to a .so or .dll file with a unique stem (e.g. model2lj239wsfo.so). This unique shared object is loaded into the R process for use with the model.getLoadedDLLs()), are attempted to be dyn.unloaded.mread or mcode), if there are no changes to the source .cpp file, the source is not overwritten. In that case, make will not re-build the shared object. Using the preclean argument will force re-compilation (see R CMD SHLIB).modelheader.h and mrgsolv.h are no longer copied into the project directory. But CLINK_CPPFLAGS environment variable is modified to include <path-to-mrgsolve-package>/inst/base so that these may be linked.R CMD SHLIB build process always uses intern=TRUE so that output is suppressed on both Windows and mac/unix. The user may still request to view build output with the ignore.stdout argument.project directory to look for C++ header files. When including a header file that may change from build to build, always run with preclean=TRUE.mread.rate > 0 and amt==0.amt (issue 43).evid 4 were not properly implemented. While investigating that issue, also found similar issue with evid 4 infusions getting scheduled with addl (issue 31).ev to avoid unintended issues in evaluation (issue 29).mcode function as alternative to using mread when your model is written in an R string. Note the order of the arguments: first model, then code, then project. project defaults to tempdir.mod <- mcode("mymodel", code). The equivalent mread call is: mod <- mread("mymodel", tempdir(),code).carry.out() and Req() now take newname = oldname as input. Use this syntax in carry.out when you want to copy a column from the input data set into the simulated data set, changing the column to newname from oldname.Req when you want to change the names of compartments or output variables specified in $TABLE / $CAPTURE.pkmodel function for easy loading and simulating from 1- and 2-compartment models (issue 39).$PKMODEL for simulating PK model with analytical solutions. The main option for this block is ncmt, which picks the number of compartments for the pk model. See ?PKMODEL for more information and other options (issue 34).code attribute to mrgmod objects. The actual source code stays with the model object. see was modified to look at x@code first when showing the model code.get_tokens), a wrapper for the boost tokenizer) to help checking the model specification file.$FIXED are now implemented as C++ preprocessor directives by default rather than const double variables. Use $SET fixed_type = "define" or $SET fixed_type = "const" to select between the approaches.mindt attribute to mrgmod objects with default value of .Machine$double.eps*10. When the problem includes an infusion, the calculated end of the infusion may come too close to another record. Usually the solver will fail with the message DLSODA- TOUT(=R1) too close to T(=R2) to start integration.. To fix this, set mindt to be greater than zero but small … maybe 1E-12. When mindt is greater than zero and tto - tfrom (the times of two adjacent records) is less than mindt, mrgsolve will set tto equal to tfrom (issue 9).zero.re didn’t properly update the $SIGMA list when one matrix was named and another was unnamed. This has been fixed.ss=1 caused mrgsolve/R to crash when the infusion duration was equal to or some multiple of the dosing interval. (issue 19)F_CENT to zero gave undefined behavior.F_CMT is set to zero and the ss flag is set to 1. (issue 22)evid=4 (reset the system and dose)addl > 0 reset the system for all subsequent doses. Additional doses coming from records with evid=4 will not do system reset. (issue 23)$NMXML (see ?nmxml) that are easier to understand and consistent with new prefixes and labels for ETA and EPS. name argument is removed. Use tname (to provide a prefix for THETAs), oname (to name the OMEGA matrix), and sname (to name the SIGMA matrix) instead. In general, set theta to be TRUE to import THETAs, set omega to be TRUE to import OMEGA, and set sigma to be TRUE to import SIGMA.tname, oname, and sname will imply theta=TRUE, omega=TRUE, and sigma=TRUE, respectively.DEPOT use: F_DEPOT (bioavailability), ALAG_DEPOT (dosing lag time), D_DEPOT (infusion duration), and / or R_DEPOT (infusion rate). (issue 13)DLSODA fails, including clear identification if the value of istate, which is 2 when the solver succeeds and negative when the solver fails.labels and prefix options to $OMEGA and $SIGMA. These allow descriptive aliases for ETAs … e.g. using ETA_CL rather than ETA(1).dplyr::slice method for mrgsims objects (issue 11)mread: quiet. Setting quiet to TRUE will prevent printing messages when mread is called. The default is getOptions("mrgsolve_mread_quiet",FALSE) … so you can call options(mrgsolve_mread_quiet = TRUE) to globally turn off messages from mread.