Nonmem-style data set. If using 'TAPD' an 'EVID' column must contain 1 for dosing records.

A numerical vector with simulation times. Can also be a data.frame in which case it must contain a 'TIME' column and is merged with 'data'.

A numerical vector with simulation times, relative to previous dose. When this is used, 'data' must contain rows with 'EVID=1' events and a 'TIME' column. 'TAPD' can also be a data.frame in which case it must contain a 'TAPD' column and is merged with 'data'.

The compartment in which to insert the EVID=2 records. Required if 'CMT' is a column in 'data'. If longer than one, the records will be repeated in all the specified compartments. If a data.frame, covariates can be specified.

The value to put in the 'EVID' column for the created rows. Default is 2 but 0 may be prefered even for simulation.

Optionally provide a single value to be assigned to the 'DV' column. The default is to assign nothing which will result in 'NA' as samples are stacked ('rbind') with 'data'. If you assign a different value in 'DV', the default value of 'EVID' changes to '0', and 'MDV' will be '0' instead of '1'. An example where this is useful is when generating datasets for '$DESIGN' where 'DV=0' is often used.

The name of the column in 'data' that holds the unique subject identifier.

Only relevant - and likely not needed - if data contains ADDL and II columns. If those columns are included, 'NMaddSamples()' will use 'NMdata::NMexpanDoses()' to evaluate the time of each dose. Other than the 'data' argument, 'NMaddSamples()' relies on the default 'NMexpanDoses()' argument values. If this is insufficient, you can specify other argument values in a list, or you can call 'NMdata::NMexpanDoses()' manually before calling 'NMaddSamples()'.

If 'TRUE' (default), events are reduced to unique time points before insertion. Sometimes, it's easier to combine sequences of time points that overlap (maybe across 'TIME' and 'TAPD'), and let 'NMaddSamples()' clean them. If you want to keep your duplicated events, use 'unique=FALSE'.

If TIME and/or 'TAPD' are 'data.frame's and contain other columns than 'TIME' and/or 'TAPD', those will by default follow the 'TIME'/'TAPD' records. Think of them as record-level variables, like 'VISIT'. The exception is 'col.id' - if the subject identifier is present, it will be merged by. If additional columns should be used to merge by, you can use the 'by' argument. This is useful to generate differentiated sampling schemes for subsets of subjects (like regimen="SAD" and regimen="MAD"). If no columns in 'TIME' and/or 'TAPD' should not be merged by, use 'by=FALSE'. You can also specify selected 'by' variables like 'by="ID"' or 'by=c("ID","regimen")' See examples.

Suppress messages? Default is 'FALSE'.

The default is to return data as a 'data.frame'. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use 'as.fun="data.table"'. The default can be configured using 'NMdataConf()'.

Deprecated. Use 'data'.

Deprecated. Use 'TIME'.

Deprecated. Use 'by'.

The time of the dosing events. Required.

vector or data.frame with amounts amount. Required.

The event ID to use for doses. Default is to use EVID=1, but EVID might also be wanted.

Compartment number. Default is to dose into CMT=1. Use 'CMT=NA' or 'CMT=NULL' to omit in result.

Number of additional dose events. Must be in combination with and consistent with II. Notice if of length 1, only applied to last event in each regimen.

Dosing frequency of additional events specified in 'ADDL'. See 'ADDL' too.

Infusion rate. Optional.

steady-state flag. Optional.

A list of ADDL and II that will be applied to last dose. This may be prefered if II and ADDL depend on covariates - see examples. Optional.

If ADDL and II are of length 1, apply only to last event of a regimen? The default is 'TRUE'.

Default is to denote the dosing regimens by an ID column. The name of the column can be modified using this argument. Use 'col.id=NA' to omit the column altogether. The latter may be wanted if repeating the regimen for a number of subjects after running 'NMcreateDoses()'.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

A data.table with at least 'i', 'j' and 'value' columns. See 'NMdata::NMreadExt' and the pars element returned by that function. Must at least have columns 'i', 'j', 'value', 'iblock', 'blocksize', 'FIX'.

If 'TRUE', all values are printed as one block. If 'FALSE' (default), matrix will be separeted into blocks based on position non-zero off-diagonal values. Generally speaking, for 'OMEGA' matrices (var-cov matrices for ETAs), this should be 'FALSE', and for variance-covariance matrices (like 'THETAP'), this should be 'TRUE'.

Include 'FIX' for all lines? If 'FALSE', fixing will not be modified. Notice, 'fix=TRUE' will fix everything - individual parameters cannot be controlled. For finer control and way more features, see 'NMdata::NMwriteInits()'.

The matrix type. 'OMEGA' or 'SIGMA' - case in-sensitive. Will be used to print say '$OMEGA' in front of each line.

File paths to the models (control streams) to run nonmem on. See file.pattern too.

Alternatively to files, you can supply a regular expression which will be passed to list.files as the pattern argument. If this is used, use dir argument as well. Also see data.file to only process models that use a specific data file.

If file.pattern is used, dir is the directory to search for control streams in.

Use the sge queing system. Default is TRUE. Disable for quick models not to wait for the queue to run the job.

A function of the model file path to generate the path in which to archive the input data as RDS. Set to FALSE not to archive the data.

Number of cores to use if sending to the cluster. This will only be used if method.execute="psn", and sge=TRUE. Default is 64.

The directory in which the data file is stored. This is normally not needed as data will be found using the path in the control stream. This argument may be removed in the future since it should not be needed.

Wait for process to finish before making R console available again? This is useful if calling NMexec from a function that needs to wait for the output of the Nonmem run to be available for further processing.

The path to the nonmem executable. Only used if method.execute="direct" or method.execute="nmsim" (which is not default). If this argument is not supplied, NMexec will try to run nmfe75, i.e. this has to be available in the path of the underlying shell. The default value can be modified using NMdata::NMdataConf, like NMdataConf(path.nonmem="/path/to/nonmem")

Only run model(s) if control stream or data updated since last run?

A function of the path to the control stream ('file.mod') that generates bash code to be evaluated once Nonmem is done. This can be used to automatically run a goodness-of-fit script or a simulation script after model estimation.

How to run Nonmem. Must be one of 'psn', 'nmsim', or 'direct'.

• psn PSN's execute is used. This supports parallel Nonmem runs. Use the nc argument to control how many cores to use for each job. For estimation runs, this is most likely the better choice, if you have PSN installed. See dir.psn argument too.

• nmsim Creates a temporary directory and runs Nonmem inside that directory before copying relevant results files back to the folder where the input control stream was. If sge=TRUE, the job will be submitted to a cluster, but parallel execution of the job itself is not supported. See path.nonmem argument too.

• direct Nonmem is called directly on the control stream. This is the simplest method and is the least convenient in most cases. It does not offer parallel runs and leaves all the Nonmem output files next to the control streams.

See 'sge' as well.

additional options that will be passed to nmfe. It is only used when path.nonmem is available (directly or using 'NMdataConf()'). Default is "-maxlim=2" For PSN, see 'args.psn.execute'.

The directory in which to find PSN executables. This is only needed if these are not searchable in the system path, or if the user should want to be explicit about where to find them (i.e. want to use a specific installed version of PSN).

A character string with arguments passed to execute. Default is "-model_dir_name -nm_output=coi,cor,cov,ext,phi,shk,xml".

In case method.execute="nmsim", this argument specifies files to be copied into the temporary directory before Nonmem is run. Input control stream and simulation input data does not need to be specified.

The degree of cleaning (file removal) to do after Nonmem execution. If 'method.execute=="psn"', this is passed to PSN's 'execute'. If 'method.execute=="nmsim"' a similar behavior is applied, even though not as granular. NMsim's internal method only distinguishes between 0 (no cleaning), any integer 1-4 (default, quite a bit of cleaning) and 5 (remove temporary dir completely).

Before running, should existing results files be backed up in a sub directory? If not, the files will be deleted before running.

Suppress messages on what NMexec is doing? Default is FALSE.

Suppress terminal output from 'Nonmem'. This is likely to only work on linux/unix systems.

A charachter string, either \"windows\" or \"linux\" - case insensitive. Windows is only experimentally supported. Default is to use Sys.info()[["sysname"]].

Path to a Nonmem input control stream.

Path to Nonmem executable. You may want to control this with NMdata::NMdataConf.

Files needed to run the control stream. This cold be a .phi file from which etas will be read. Notice, input data set will be handled automatically, you do not need to specify that.

If NULL, data will be copied into the temporary directory, and Nonmem will read it from there. If not NULL, dir.data must be the relative path from where Nonmem is run to where the input data file is stored. This would be ".." if the run directory is created in a directory where the data is stored.

The degree of cleaning (file removal) to do after Nonmem execution. If 'method.execute=="psn"', this is passed to PSN's 'execute'. If 'method.execute=="nmsim"' a similar behavior is applied, even though not as granular. NMsim's internal method only distinguishes between 0 (no cleaning), any integer 1-4 (default, quite a bit of cleaning) and 5 (remove temporary dir completely).

A file path to read from. Normally a .mod or .lst. See lines and text as well.

Text lines to process. This is an alternative to using the file and text arguments.

Use this argument if the text to process is one long character string, and indicate the line separator with the linesep argument. Use only one of file, lines, and text.

The name of section to extract. Examples: "INPUT", "PK", "TABLE", etc. It can also be result sections like "MINIMIZATION".

The section denoted as a string compatible with regular expressions. "$" (remember to escape properly) for sections in .mod files, "0" for results in .lst files.

A regular expression to capture the end of the section. The default is to look for the next occurrence of char.section.

If "text", plain text lines are returned. If "idx", matching line numbers are returned. "text" is default.

Keep empty lines in output? Default is FALSE. Notice, comments are removed before empty lines are handled if 'keep.comments=TRUE'.

Keep the section name in output (say, "$PROBLEM") Default is TRUE. It can only be FALSE, if return="text".

Default is to keep comments. If FALSE, the will be removed.

If multiple hits, concatenate into one. This will most often be relevant with name="TABLE". If FALSE, a list will be returned, each element representing a table. Default is TRUE. So if you want to process the tables separately, you probably want FALSE here.

If TRUE, leading and trailing are removed, and multiplied succeeding white spaces are reduced to single white spaces.

If asOne=FALSE, do you want the result to be simplified if only one table is found? Default is TRUE which is desirable for interactive analysis. For programming, you probably want FALSE.

Default is to search for exact matches of 'section'. If FALSE, only the first three characters are matched. E.G., this allows "ESTIMATION" to match "ESTIMATION" or "EST".

Either mod, res or NULL. mod is for information that is given in .mod (.lst file can be used but results section is disregarded). If NULL, NA or empty string, everything is considered.

If using the text argument, use linesep to indicate how lines should be separated.

Deprecated. See keep.empty.

Deprecated. See keep.name.

Deprecated. See keep.comments.

Deprecated. See as.one.

number of cores wanted

The file path to write the result to

Path to a control stream. See 'lines' too.

A control stream as text lines. Use this or 'file'.

The section to read. Typically, "theta", "omega", or "sigma". Default is those three.

By default (when return="pars", a parameter table with initial values, FIX, lower and upper bounds etc. In most cases, that is what is needed to derive information about parameter definitions. If return="all", two additional tables are returned which can be used if the aim is to modify and write the resulting parameters to a control stream.

See ?NMscanData

A file path to read from. Normally a .mod or .lst. See lines also.

Text lines to process. This is an alternative to using the file argument.

Deprecated, use 'lines'. Use this argument if the text to process is one long character string, and indicate the line separator with the linesep argument (handled by NMextractText). Use only one of file, lines, and text.

The name of section to extract without "$". Examples: "INPUT", "PK", "TABLE", etc. Not case sensitive.

If "text", plain text lines are returned. If "idx", matching line numbers are returned. "text" is default.

Keep empty lines in output? Default is FALSE. Notice, comments are removed before empty lines are handled if 'keep.comments=TRUE'.

Keep the section name in output (say, "$PROBLEM") Default is FALSE. It can only be FALSE, if return="text".

Default is to keep comments. If FALSE, the will be removed. See keep.empty too. Notice, there is no way for NMreadSection to keep comments and also drop lines that only contain comments.

If multiple hits, concatenate into one. This will most often be relevant with name="TABLE". If FALSE, a list will be returned, each element representing a table. Default is TRUE. So if you want to process the tables separately, you probably want FALSE here.

If TRUE, leading and trailing are removed, and multiplied succeeding white spaces are reduced to single white spaces.

If asOne=FALSE, do you want the result to be simplified if only one section is found? Default is TRUE which is desirable for interactive analysis. For programming, you probably want FALSE.

Deprecated. See keep.empty.

Deprecated. See keep.name.

Deprecated. See keep.comments.

Deprecated. See as.one.

Additional arguments passed to NMextractText

Path to the simulation-specific rds file generated by NMsim, typically called 'NMsim_MetaData.rds'. Can also be a table of simulation runs as stored in 'rds' files by 'NMsim'. The latter should almost never be used.

If found, check whether 'fst' file modification time is newer than 'rds' file. The 'fst' is generated based on information in ‘rds', but notice that some systems don’t preserve the file modification times. Becasue of that, 'check.time' is 'FALSE' by default.

By default, 'NMreadSim' will use information about the relative path from the results table file ('_MetaData.rds') to the Nonmem simulation results. If these paths have changed, or for other reasons this doesn't work, you can use the 'dir.sims' argument to specify where to find the Nonmem simulation results. If an '.fst' file was already generated and is found next to the '_MetaData.rds', the path to the Nonmem simulation results is not used.

If simulations seem to not be done yet, wait for them to finish? If not, an error will be thrown. If you choose to wait, the risk is results never come. 'NMreadSim' will be waiting for an 'lst' file. If Nonmem fails, it will normally generate an 'lst' file. But if 'NMTRAN' fails (checks of control stream prior to running Nonmem), the 'lst' file is not generated. Default is not to wait.

Turn off some messages about what is going on? Default is to report the messages.

Track progress? Default is 'TRUE' if 'quiet' is FALSE and more than one model is being read. The progress tracking is based on the number of models completed/read, not the status of the individual models.

Skip models where results are not available? Default is 'FALSE' meaning an error will be thrown if one or more models do not have completed results.

If results are read successfully, remove temporary simulation results files? This can be useful after a script is developed and intermediate debugging information is not needed. It cleans up and saves significant disk space.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

Path to the simulation-specific rds file generated by NMsim, typically called 'NMsim_MetaData.rds'. Can also be a table of simulation runs as stored in 'rds' files by 'NMsim'. The latter should almost never be used.

If found, check whether 'fst' file modification time is newer than 'rds' file. The 'fst' is generated based on information in ‘rds', but notice that some systems don’t preserve the file modification times. Becasue of that, 'check.time' is 'FALSE' by default.

By default, 'NMreadSim' will use information about the relative path from the results table file ('_MetaData.rds') to the Nonmem simulation results. If these paths have changed, or for other reasons this doesn't work, you can use the 'dir.sims' argument to specify where to find the Nonmem simulation results. If an '.fst' file was already generated and is found next to the '_MetaData.rds', the path to the Nonmem simulation results is not used.

If simulations seem to not be done yet, wait for them to finish? If not, an error will be thrown. If you choose to wait, the risk is results never come. 'NMreadSim' will be waiting for an 'lst' file. If Nonmem fails, it will normally generate an 'lst' file. But if 'NMTRAN' fails (checks of control stream prior to running Nonmem), the 'lst' file is not generated. Default is not to wait.

Skip models where results are not available? Default is 'FALSE' meaning an error will be thrown if one or more models do not have completed results.

Turn off some messages about what is going on? Default is to report the messages.

Track progress? Default is 'TRUE' if 'quiet' is FALSE and more than one model is being simulated. The progress tracking is based on the number of models completed, not the status of the individual models.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

If found, check whether 'fst' file modification time is newer than 'rds' file. The 'fst' is generated based on information in ‘rds', but notice that some systems don’t preserve the file modification times. Becasue of that, 'check.time' is 'FALSE' by default.

By default, 'NMreadSim' will use information about the relative path from the results table file ('_MetaData.rds') to the Nonmem simulation results. If these paths have changed, or for other reasons this doesn't work, you can use the 'dir.sims' argument to specify where to find the Nonmem simulation results. If an '.fst' file was already generated and is found next to the '_MetaData.rds', the path to the Nonmem simulation results is not used.

If simulations seem to not be done yet, wait for them to finish? If not, an error will be thrown. If you choose to wait, the risk is results never come. 'NMreadSim' will be waiting for an 'lst' file. If Nonmem fails, it will normally generate an 'lst' file. But if 'NMTRAN' fails (checks of control stream prior to running Nonmem), the 'lst' file is not generated. Default is not to wait.

Turn off some messages about what is going on? Default is to report the messages.

Skip models where results are not available? Default is 'FALSE' meaning an error will be thrown if one or more models do not have completed results.

Track progress? Default is 'TRUE' if 'quiet' is FALSE and more than one model is being read. The progress tracking is based on the number of models completed/read, not the status of the individual models.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

a data set or a fst file

A path to an fst file or a data set

Control stream path.

Character vector with control stream file.

A data.frame with new initial estimates, same style as returned by NMdata::NMreadExt. Column' par.type' can contain elements THETA, OMEGA, SIGMA.

Passed to NMdata::NMwriteSection. This is important for NMreplaceInits to run at all.

Just the file name, not including path

A data.frame containing model paths etc as created by NMsim().

Number of seeds in each simulation control stream. Default is to match length of dist.

Distribution of random sources. These character strings will be pasted directly into the Nonem control streams after the seed values. Default is "" which means one normal distribution. dist=c("","UNIFORM") will give two seeds with random sources following a normal and a uniform distribution.

Optionally, seed values. This can be a data.frame with as many columns as random sources.

Path(s) to the input control stream(s) to run the simulation on. The output control stream is for now assumed to be stored next to the input control stream and ending in .lst instead of .mod. The .ext file must also be present. If simulating known subjects, the .phi is necessary too.

The simulation data as a data.frame or a list of data.frames. If a list, the model(s) will be run on each of the data sets in the list.

Number of subproblems to use as SUBPROBLEMS in $SIMULATION block in Nonmem. The default is subproblem=0 which means not to use SUBPROBLEMS.

If simulation results found on file, should they be used? If TRUE and reading the results fail, the simulations will still be rerun.

A value passed to set.seed(). It is recommended to use seed.R rather than calling set.seed() manually because the seed can then be captured and stored by NMsim() for reproducibility. See seed.nm for finer control of the seeds that are used in the Nonmem control streams.

Control Nonmem seeds. If a numeric, a vector or a 'data.frame', these are used as the the seed values (a single value or vector will be recycled so make sure the dimesnsions are right, the number of columns in a data.frame will dictate the number of seeds in each Nonmem control stream. Use a list with elements 'values', and 'dist' and others for detailed control of the random sources. See ?NMseed for details on what arguments can be passed this way.

Default is to draw seeds betwen 0 and 2147483647 (the values supported by Nonmem) for each simulation. You can pass a function that will be evaluated (say to choose a different pool of seeds to draw from).

To avoid changing an exisiting seed in a control stream, use seed.nm="asis".

In case method.sim=NMsim_EBE, seeds are not used.

Give all filenames related to the simulation a suffix. A short string describing the sim is recommended like "ph3_regimens".

Variables to be printed in output table as a character vector or a space-separated string of variable names. The default is to export the same tables as listed in the input control stream. If table.vars is provided, all output tables in estimation control streams are dropped and replaced by a new one with just the provided variables. If many variables are exported, and much fewer are used, it can speed up NMsim significantly to only export what is needed (sometimes this is as little as "PRED IPRED"). Nonmem writes data slowly so reducing output data can make a very big difference in execution time. See table.options too.

A character vector or a string of space-separated options. Only used if table.vars is provided. If constructing a new output table with table.vars the default is to add two options, NOAPPEND and NOPRINT. You can modify that with table.options. Do not try to modify output filename - NMsim takes care of that. See 'table.format' too.

A format for '$TABLE'. Only used if 'table.vars' is provided. Default is "s1PE16.9". NMsim needs a high-resolution format. The Nonmem default "s1PE11.4" is insufficient for simulation data sets of 1e5 rows or more.

Variables from input data that should be included in results. Default is to include everything. If working with large data sets, it may be wanted to provide a subset of the columns here. If doing very large simulations, this may also be a way to save memory.

A function (not quoted) that creates the simulation control stream and other necessary files for a simulation based on the estimation control stream, the data, etc. The default is called NMsim_default which will replace any estimation and covariance step by a simulation step. See details section on oter methods, and see examples and especially vignettes on how to use the different provided methods.

Run with all ETAs fixed to zero? Technically all ETAs=0 is obtained by replacing $OMEGA by a zero matrix. Default is 'FALSE'.

Control the parameter values. 'inits' is a list. The 'method' element controls which method is used to do this, and this corresponds to the old 'method.update.inits' argument. If using the new 'method=nmsim' you can specify parameter values, fix/unfix them, and edit lower and upper limits for estimation.

• 'method="nmsim"' (default) A highly flexible internal method, allows for modification of the parameter values. All other elements in 'inits' are passed to 'NMwriteInits()'. Example where 'THETA(2)' is customized: 'inits=list("THETA(2)"=list(init=1.3))'. See '?NMwriteInits' too.

• 'method="psn"' Uses PSN's "update_inits". Requires a functioning PSN installation and possibly that dir.psn is correctly set. The advantages of this method are that it keeps comments in the control stream and that it is a method known to many.

• 'method="simple"' Uses a simple internal method to update the parameter values based on the ext file. The advantages are it does not require PSN, and that it does not rely on code-interpretation for generation of simulation control streams. "simple" fixes the whole OMEGA and SIGMA matrices as single blocks which is robust because it avoids any interpretation of BLOCK structure or other code in the control streams. The downside is it strips all comments, and generally makes the $OMEGA and $SIGMA sections of the simulation control streams less easy to read. "simple" can be used as a fallback in case of any issues with 'method="nmsim"'.

• 'method="none"' Do nothing. This is useful if the model to simulate has not been estimated but parameter values have been manually put into the respective sections in the control stream.

See also 'file.ext' which can now be handled by 'inits' too. This change collects the update of the "initial" parameter values into one interface rather than multiple arguments.

Named list of additional control stream section edits. Note, these can be functions that define how to edit sections. This is an advanced feature which is not needed to run most simulations. It is however powerful for some types of analyses, like modifying parameter values. See vignettes for further information.

Edit data filters ('IGNORE'/'ACCEPT' statements) before running model. This should normally only be used if no data set is provided. It can be useful if simulating for a VPC but a different subset of data needs to be simulated than the one used for estimation. A common example on this is inclusion of BLQ's in the VPC even if they were excluded in the estimation. See '?NMreadFilters' which returns a table you can edit and pass to 'filters'. You can also just pass a string representing the full set of filters to be used. If you pass a string, consider including "IGN=@" to avoid character rows, like the column headers.

If needed, adjust the '$SIZES' section by providing a list of arguments to 'NMupdateSizes()'. Example: ‘sizes=list(PD=80)'. See '?NMupdateSizes' for details. Don’t use arguments like 'file.mod' and 'newfile' which are handled internally.

The path to the Nonmem executable to use. The could be something like "/usr/local/NONMEM/run/nmfe75" (which is a made up example). No default is available. You should be able to figure this out through how you normally execute Nonmem, or ask a colleague.

Submit to cluster? Default is not to, but this is very useful if creating a large number of simulations, e.g. simulate with all parameter estimates from a bootstrap result.

Number of cores used in parallelization. Only used if 'sge=TRUE'.

Execute the simulation or only prepare it? 'execute=FALSE' can be useful if you want to do additional tweaks or simulate using other parameter estimates.

The path to the script where this is run. For stamping of dataset so results can be traced back to code.

A list defining transformations to be applied after the Nonmem simulations and before plotting. For each list element, its name refers to the name of the column to transform, the contents must be the function to apply.

reorder columns by calling NMdata::NMorderColumns before saving dataset and running simulations? Default is TRUE.

Specify how to call Nonmem. Options are "psn" (PSN's execute), "nmsim" (an internal method similar to PSN's execute), and "direct" (just run Nonmem directly and dump all the temporary files). "nmsim" has advantages over "psn" that makes it the only supported method when type.sim="NMsim_EBE". "psn" has the simple advantage that the path to nonmem does not have to be specified if "execute" is in the system search path. So as long as you know where your Nonmem executable is, "nmsim" is recommended. The default is "nmsim" if path.nonmem is specified, and "psn" if not.

additional options that will be passed to nmfe. It is only used when path.nonmem is available (directly or using 'NMdataConf()'). Default is "-maxlim=2" For PSN, see 'args.psn.execute'.

Include 'NMREP' as counter of subproblems? The default is to do so if 'subproblems>0'. This will insert a counter called 'NMREP' in the '$ERROR' section and include that in the output table(s). At this point, nothing is done to avoid overwriting existing variables.

Only used if 'data' is provided. Use this if you are including an exclusion flag column in data. However, what NMsim will then do is to require that column to equal '0' (zero) for the rows to be simulated. It is often better to subset the data before simulation. See 'filters' too.

The directory in which to find PSN's executables ('execute' and 'update_inits'). The default is to rely on the system's search path. So if you can run 'execute' and 'update_inits' by just typing that in a terminal, you don't need to specify this unless you want to explicitly use a specific installation of PSN on your system.

A charachter string that will be passed as arguments PSN's 'execute'. The default is "-model_dir_name -nm_output=coi,cor,cov,ext,phi,shk,xml -nmfe_options=\"-maxlim=2\"" in addition to the "-clean" based on the 'clean' argument. Notice, if 'path.nonmem' is provided, the default is not to use PSN.

If execute=TRUE&sge=FALSE, NMsim will normally read the results using NMreadSim. Use this argument to pass additional arguments (in a list) to that function if you want the results to be read in a specific way. This can be if the model for some reason drops rows, and you need to merge by a row identifier. You would do 'args.NMscanData=list(col.row="ROW")' to merge by a column called 'ROW'. This is only used in rare cases.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

A charachter string, either "windows" or "linux" - case insensitive. Windows is only experimentally supported. Default is to use Sys.info()[["sysname"]].

The directory in which NMsim will store all generated files. Default is to create a folder called 'NMsim' next to 'file.mod'.

Provide a path to a directory in which to save rds files with paths to results. Default is to use dir.sims. After running 'NMreadSim()' on these files, the original simulation files can be deleted. Hence, providing both 'dir.sims' and 'dir.res' provides a structure that is simple to clean. 'dir.sims' can be purged when 'NMreadSim' has been run and only small 'rds' and 'fst' files will be kept in 'dir.res'. Notice, in case multiple models are simulated, multiple 'rds' (to be read with 'NMreadSim()') files will be created by default. In cases where multiple models are simulated, see 'file.res' to get just one file refering to all simulation results.

Path to an rds file that will contain a table of the simulated models and other metadata. This is needed for subsequently retrieving all the results using 'NMreadSim()'. The default is to create a file called 'NMsim_..._MetaData.rds' under the dir.res directory where ... is based on the model name. However, if multiple models (file.mod) are simulated, this will result in multiple rds files. Specifying a path ensures that one rds file containing information about all simulated models will be created. Notice if file.res is supplied, dir.res is not used.

Wait for simulations to finish? Default is to do so if simulations are run locally but not to if they are sent to the cluster. Waiting for them means that the results will be read when simulations are done. If not waiting, path(s) to 'rds' files to read will be returned. Pass them through 'NMreadSim()'. Conveniently, NMreadSim() also takes the 'wait' argument too, allowing flexibility to run Nonmem in the background, and then read the results, still waiting for Nonmem to finish.

A character string to be pasted into $SIMULATION. This must not contain seed or SUBPROBLEM which is handled separately. Default is to include "ONLYSIM". You cannot avoid that using 'text.sim'. If needed, you can use 'onlysim=FALSE' which will be passed to 'NMsim_default()'.

Add a column called 'DV' to input data sets if a column of that name is not found? Nonmem is generally dependent on a 'DV' column in input data but this is typically uninformative in simulation data sets and hence easily forgotten when generating simulation data sets. If auto.dv=TRUE and no 'DV' column is found, 'DV=NA' will be added. In this case ('auto.dv=TRUE' and no 'DV' column found) a 'MDV=1' column will also be added if none found.

The degree of cleaning (file removal) to do after Nonmem execution. If 'method.execute=="psn"', this is passed to PSN's 'execute'. If 'method.execute=="nmsim"' a similar behavior is applied, even though not as granular. NMsim's internal method only distinguishes between 0 (no cleaning), any integer 1-4 (default, quite a bit of cleaning) and 5 (remove temporary dir completely).

If TRUE (default) this will wipe the simulation directory before running new simulations. The directory that will be emptied is _not_ dir.sims where you may keep many or all your simulations. It is the subdirectory named based on the run name and name.sim. The reason it is advised to wipe this directory is that if you in a previous simulation created simulation runs that are now obsolete, you could end up reading those too when collecting the results. NMsim will delete previously generated simulation control streams with the same name, but this option goes further. An example where it is important is if you first ran 1000 replications, fixed something and now rand 500. If you choose FALSE here, you can end up with the results of 500 new and 500 old simulations.

If the directories specified in dir.sims and dir.res do not exists, should it be created? Default is TRUE.

If TRUE, messages from what is going on will be suppressed.

Silent console messages from Nonmem? The default behaviour depends. It is FALSE if there is only one model to execute and 'progress=FALSE'.

Track progress? Default is 'TRUE' if 'quiet' is FALSE and more than one model is being simulated. The progress tracking is based on the number of models completed, not the status of the individual models.

Check the provided control streams for contents that may cause issues for simulation. Default is 'TRUE', and it is only recommended to disable this if you are fully aware of such a feature of your control stream, you know how it impacts simulation, and you want to get rid of warnings.

For development purposes - users do not need this argument. Controls what format the complete input data set is saved in. Possible values are 'rds' (default), 'fst' (experimental) and 'csv'. 'fst' may be faster and use less disk space but factor levels may be lost from input data to output data. 'csv' will also lead to loss of additional information such as factor levels.

Deprecated. Use 'table.vars' and 'table.options' instead.

Deprecated. Use name.sim instead.

Deprecated. See seed.R and seed.nm.

Deprecated. Use 'inits=list(file.ext="path/to/file.ext")' instead. Optionally provide a parameter estimate file from Nonmem. This is normally not needed since 'NMsim' will by default use the ext file stored next to the input control stream (replacing the file name extension with '.ext'). If using method.update.inits="psn", this argument cannot be used.

Deprecated, please migrate to 'inits' instead. The initial values of all parameters are by updated from the estimated model before running the simulation. NMsim can do this with a native function or use PSN to do it - or the step can be skipped to not update the values.

Deprecated. Use modify instead.

Deprecated. Use modify instead.

Additional arguments passed to method.sim.

A control stream to check

The control stream as text lines. Only use of of 'file.mod' and 'lines'.

See ?NMsim

See ?NMsim

See ?NMsim

Throw an error if the configuration does not seem to match system.

See ?NMsim

The path to the control stream to be edited. This function overwrites the contents of the file pointed to by file.sim.

Path to the path to the original input control stream provided as 'file.mod' to 'NMsim()'.

See ?NMsim.

A phi file to take the known subjects from. The default is to replace the filename extension on file.mod with .phi. A different .phi file would be used if you want to reuse subjects simulated in a previous simulation.

If TRUE, just the text will be returned, and resulting control stream is not written to file.

The path to the control stream to be edited. This function overwrites the contents of the file pointed to by file.sim.

Path to the path to the original input control stream provided as 'file.mod' to 'NMsim()'.

Included for compatibility with 'NMsim()'. Not used.

Used in $PRIOR NWPRI PLEV=0.999. This is a NONMEM argument to the NWPRI subroutine. When PLEV < 1, a value of THETA will actually be obtained using a truncated multivariate normal distribution, i.e. from an ellipsoidal region R1 over which only a fraction of mass of the normal occurs. This fraction is given by PLEV.

Additional arguments passed to 'NMsim_default()'.

The path to the control stream to be edited. This function overwrites the contents of the file pointed to by file.sim.

Path to the path to the original input control stream provided as 'file.mod' to 'NMsim()'.

Included for compatibility with 'NMsim()'. Not used.

Number of replications wanted. The default is 1. If greater, multiple control streams will be generated.

When 'ext' is not used, parameters are sampled, using 'samplePars()'. 'method' must be either 'mvrnorm' or 'simpar'. Only used when 'ext' is not provided.

Parameter values in long format as created by 'readParsWide' and 'NMdata::NMreadExt'.

If supplied, a path to an rds file where the parameter values used for simulation will be saved.

Additional arguments passed to 'NMsim_default()'.

See ?NMsim.

See ?NMsim.

See ?NMsim.

See ?NMsim.

See ?NMsim.

See ?NMsim.

Number of replications wanted. The default is 1. If greater, multiple control streams will be generated.

Include 'ONLYSIM' in '$SIMULATION'? Default is 'TRUE'. Only applied when 'replace.sim='TRUE'.

If there is a $SIMULATION section in the contents of file.sim, should it be replaced? Default is yes. See the list.section argument to NMsim for how to provide custom contents to sections with NMsim instead of editing the control streams beforehand.

If TRUE, just the text will be returned, and resulting control stream is not written to file.

Everything passed to NMsim_EBE()

See ?NMsim.

See ?NMsim.

See ?NMsim.

If TRUE, just the text will be returned, and resulting control stream is not written to file.

a control stream, path or 'NMctl' object.

What section to update

Model name

The file name extension of the file name to be updated (e.g., one of "tab", "csv", "msf").

Addditional text to insert right after $SECTION. It can be additional TABLE variables.

The Nonmem parameter that specifies the file. In $TABLE, this is FILE. In $EST it's probably MSFO.

This is used to overwrite the contents of the section. The section output file name will still handled/updated.

Suppress messages? Default is 'FALSE'.

The control stream to update. Will not be edited.

Path to ext file. Default is to replace extension on 'file.mod'.

New file to generate

Path to control stream. Use 'file' or 'lines'.

Control stream as text lines. Use 'file' or 'lines'.

A data frome with filters, like returned by 'NMreadFilters()'.

If 'file' is provided, write the results to file? If 'lines' is used, 'write' cannot be used.

Path to control stream.

If 'TRUE' (default), the parameter values are updated based on the '.ext' file. The path to the '.ext' file can be specified with 'file.ext' but that is normally not necessary.

Optionally provide the path to an '.ext' file. If not provided, the default is to replace the file name extention on 'file.mod' with '.ext'. This is only used if 'update=TRUE'.

An long-format parameter table as returned by 'NMreadExt()'. Can contain multiple models if 'file.mod' does not.

A wide-format parameter table, well suited for customizing initial values, limits, and for fixing parameters. For multiple custom parameter specifications, this may be the most suitable argument.

A list of lists. Each list specifies a parameter with named elements. Must be named by the parameter name. 'lower', 'upper' and 'fix' can be supplied to modify the parameter. See examples. Notice, you can use '...' instead. 'values' may be easier for programming but other than that, most users will find '...' more intuitive.

If provided, the results are written to this file as a new input control stream.

Parameter specifications. See examples,

A path to a control stream. See also alternative 'lines' argument. Notice, if 'write' is 'TRUE' (default) and 'newfile' is not provided, 'file.mod' will be overwritten.

An optional path to write the resulting control stream to. If nothing is provided, the default is to overwrite 'file.mod'.

Control stream lines as a character vector. If you already read the control stream - say using 'NMdata::NMreadSection()', use this to modify the text lines.

The default behavior ('wipe=FALSE') is to add the '$SIZES' values to any existing values found. If SIZES parameter names are overlapping with existing, the values will be updated. If 'wipe=TRUE', any existing '$SIZES' section is disregarded.

Write results to 'newfile'?

The $SIZES parameters. Provided anything, like 'PD=40' See examples.

Parameters in long format, as returned by 'NMreadExt()'.

Elements to add.

Either "top" or "bottom". Decides if new text is prepended or appended to existing text.

The parameter, as returned by 'NMreadExt()'

Name of the model name column.

The object to add class to

The class to add (character)

Nonmem-style data set. If using 'TAPD' an 'EVID' column must contain 1 for dosing records.

A numerical vector with simulation times. Can also be a data.frame in which case it must contain a 'TIME' column and is merged with 'data'.

A numerical vector with simulation times, relative to previous dose. When this is used, 'data' must contain rows with 'EVID=1' events and a 'TIME' column. 'TAPD' can also be a data.frame in which case it must contain a 'TAPD' column and is merged with 'data'.

The compartment in which to insert the EVID=2 records. Required if 'CMT' is a column in 'data'. If longer than one, the records will be repeated in all the specified compartments. If a data.frame, covariates can be specified.

The value to put in the 'EVID' column for the created rows. Default is 2 but 0 may be prefered even for simulation.

Optionally provide a single value to be assigned to the 'DV' column. The default is to assign nothing which will result in 'NA' as samples are stacked ('rbind') with 'data'. If you assign a different value in 'DV', the default value of 'EVID' changes to '0', and 'MDV' will be '0' instead of '1'. An example where this is useful is when generating datasets for '$DESIGN' where 'DV=0' is often used.

The name of the column in 'data' that holds the unique subject identifier.

Only relevant - and likely not needed - if data contains ADDL and II columns. If those columns are included, 'addEVID2()' will use 'NMdata::NMexpanDoses()' to evaluate the time of each dose. Other than the 'data' argument, 'addEVID2()' relies on the default 'NMexpanDoses()' argument values. If this is insufficient, you can specify other argument values in a list, or you can call 'NMdata::NMexpanDoses()' manually before calling 'addEVID2()'.

If 'TRUE' (default), events are reduced to unique time points before insertion. Sometimes, it's easier to combine sequences of time points that overlap (maybe across 'TIME' and 'TAPD'), and let 'addEVID2()' clean them. If you want to keep your duplicated events, use 'unique=FALSE'.

If 'TIME' and/or 'TAPD' are 'data.frame's and contain other columns than 'TIME' and/or 'TAPD', those are by default assumed to be covariates to be merged with data. More specifically, they will be merged by when the sample times are added. If 'extras.are.covs=FALSE', they will not be merged by. Instead, they will just be kept as additional columns with specified values, aligned with the sample times.

The default is to return data as a 'data.frame'. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use 'as.fun="data.table"'. The default can be configured using 'NMdataConf()'.

Deprecated. Use 'data'.

Deprecated. Use 'TIME'.

A data set containing indiviudual predictions. Often a result of NMsim.

Path to the ext file to take the parameter estimates from.

Parameter number of parameter holding variance of the proportional error component. If ERR(1) is used for proportional error, use prop=1. Can also refer to a theta number.

Parameter number of parameter holding variance of the additive error component. If ERR(1) is used for additive error, use add=1. Can also refer to a theta number.

Should the error be added on log scale? This is used to obtain an exponential error distribution.

Use "sigma" if variances are estimated with the SIGMA matrix. Use "theta" if THETA parameters are used. See 'scale.par' too.

If log=FALSE, truncate simulated values at 0? If trunc0, returned predictions can be negative.

Denotes if parmeter represents a variance or a standard deviation. Allowed values and default value depends on 'par.type'.

• if par.type="sigma" only "var" is allowed.

• if par.type="theta" allowed values are "sd" and "var". Default is "sd".

A character string with an expression denoting a subset in which to add the residual error. Example: subset="DVID=='A'"

A number to pass to set.seed() before simulating. Default is to generate a seed and report it in the console. Use seed=FALSE to avoid setting the seed (if you prefer doing it otherwise).

The name of the column containing individual predictions.

The name of the column to be created by addResVar to contain the simulated observations (individual predictions plus residual error).

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

object to convert

Not used

Path to Nonmem-created file. Typically an output control stream.

Scan input data for updates too? Default is TRUE.

If you do want to take into account input data but avoid re-reading the information, you can pass the NMdata meta data object.

The input control stream

If files are moved around on or between file systems, the file modification time may not be reflective of the Nonmem runtime. In that case, you can choose to extract the time stamp from the output control stream. The issue is that Nonmem does not write the time zone, so you have to pass that to checkTimes if this is wanted.

a string to clean

A covariate specififed in a list. See ?expandCovLists.

See ?expandCovLists.

The subject ID column name. Necessary because quantiles sould be quantiles of distribution of covariate on subjects, not on observations (each subject contributes once).

Used for rounding of covariate values if using quantiles or if using a function to find reference.

elements as detected by 'NMreadInits()'

data set to transpose (widen)

left-hand side variables as character vector. Result will be long/vertical in these variables.

left-hand side variables as character vector. Result will be wide in these variables.

Additional arguments paseed to 'data.table::dcast()'.

arguments passed to lapply

Passed to 'forestDefineCovs()'

list of (input or output) control streams to consider

The file name or file names to modify.

A character string or a numeric to add to the file name

In case x is numeric, a number of zeros to pad before the appended number. This is useful if you are generating say more than 10 files, and your counter will be 01, 02,.., 10,... and not 1, 2,...,10,...

The separator between the existing file name (until extension) and the addition.

If 'x' is of length greater than 1, the default is to collapse the elements to a single string using 'sep' as separator. See the 'collapse' argument to '?paste'. If you want to treat them as separate strings, use 'collapse=NULL' which will lead to generation of separate file names. However, currently 'fn' or 'x' must be of length 1.

Allow 'fn' to be string(s) without extensions? Default is 'FALSE' in which case an error will be thrown if 'fn' contains strings without extensions. If 'TRUE', 'x' will be appended to fn in these cases.

Covariates provided as lists - see examples. The name of the arguement must match columns in data set. An element called ref must contain either a reference value or a function to use to derive the reference value from data (e.g. 'median'). Provide either 'values' or 'quantiles' to define the covariate values of interest (typically, the values that should later be simulated and maybe shown in a forest plot). 'label' is optional - if missing, the argument name will be used. If quantiles are requested, they are derived after requiring unique values for each subject.

A data set needed if the reference(s) value of one or more covariates is/are provided as functions (like median), or if covariate values are provided as quantiles.

The subject ID column name. Necessary because quantiles sould be quantiles of distribution of covariate on subjects, not on observations (each subject contributes once).

Used for rounding of covariate values if using quantiles or if using a function to find reference.

If 'TRUE' (default), only return one row with all reference values. If 'FALSE' there will be one such row for each covariate. When reduced to one line, all columns related to covariate-level information such as covariate name will contain 'NA' for the reference.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

Simulated data to process. This data.frame must contain must contain multiple columns, as defined by 'NMsim::forestDefineCovs()'.

A named list of functions to apply for derivation of exposure metrics.

The coverage of the confidence intervals. Default is 0.95.

a character vector of column names to perform all calculations by. This could be sampling subsets or analyte.

The default is to return data as a 'data.frame'. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use 'as.fun="data.table"'. The default can be configured using 'NMdataConf()'.

A dataset that contains "ID" and all 'ETA's. This can be obtained by 'NMdata::NMscanData'.

Path to the .phi file to be written.

If 'file' exists already, overwrite it? Default is 'FALSE'.

Path to input or output control stream.

a data.table or something to be converted to a data.table.

passed to print.data.table.

NMsim results (class 'NMsimRes').

A list

a data.table

List of coontrol streams as lines

File name to provide stem for all file names

List of objects to provide names for

If only one file path, skip numbering? Default is TRUE.

Passed to 'gsub()'

This is passed to gsub(), but ‘overwrite()'’s default behavior is the opposite of the one of 'gsub()'. Default is 'FALSE' which means that strings that are exactly matched will be replaced. This is useful because strings like 'THETA(1)' contains special characters. Use 'fixed=FALSE' to use regular expressions. Also, see other arguments accepted by 'gsub()' for advanced features.

integers to pad. They can be coded as characters already.

Optional specification of length of character strings to return. If not supplied, characters will be padded to match length of max value in x.

A vector of strings

A string to add

Aditional arguments to 'paste()'.

Output of NMsim::NMcreateMatLines. This is a string of OMEGA/SIGMA estimates that will be wrapped onto multiple lines for ease of reading in NONMEM control streams.

The summary object to be printed. See ?summary.NMsimRes

Arguments passed to other print methods.

vector of file paths. Typically to Nonmem executables.

If TRUE, an error is thrown if no paths are valid.

object to read.

Not used.

A data.frame or a path to a delimited file to be read using 'data.table::fread'.

Column containing name of the original model. By default a column called "model" will contain "Model1".

Name of the model counter, default is "model.sim". If the provided name is not found in data, it will be created as a row counter. Why needed? Each row in data represents a set of parameters, i.e. a model. In the long format result, each model will have multiple rows. Hence, a model identifier is needed to distinguish between models in results.

Defines how column names get associated with THETA, OMEGA, and SIGMA. Default is to look for "T", "O", or "S" as starting letter. If customizing, make sure each no column name will be matched by more than one criterion.

The default is to return data as a data.frame. Pass a function (say tibble::as_tibble) in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

A simulation data set with only one subject

The number of subjects to be sampled. This can be greater than the number of subjects in data.covs.

Name of the subject ID column in 'data' (default is "ID").

Name of the subject ID column in 'data.covs' (default is "ID").

The data set containing the subjects to sample covariates from.

The name of the covariates (columns) to sample from 'data.covs'.

If provided, passed to 'set.seed()'.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

Path to model control stream. Will be used for both 'NMreadExt()' and 'NMreadCov()', and extension will automatically be replaced by '.ext' and '.cov'.

Number of sets of parameter values to generate. Passed to 'simpar'.

The sampling method. Options are "mvrnorm" and "simpar". Each have pros and cons. Notice that both methods are fully automated as long as ".ext" and ".cov" files are available from model estimation.

seed value passed to set.seed().

The returned data set format "ext" (default) or "wide". "ext" is a long-format, similar to what 'NMdata::NMreadExt()' returns.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

Path to model control stream. Will be used for both 'NMreadExt()' and 'NMreadCov()', and extension will automatically be replaced by '.ext' and '.cov'.

Number of sets of parameter values to generate. Passed to 'simpar'.

"ext" (default) or "wide".

seed value passed to set.seed().

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

Passed to 'NMdata::NMreadExt()'. Path to ext file. By default, 'NMreadExt()' uses a'auto.ext=TRUE' which means that the file name extension is replaced by '.ext'. If your ext file name extension is not '.ext', add 'auto.ext=FALSE' (see ...).

Number of subjects to generate

Optional seed. Will be passed to 'set.seed'. Same thing as running 'set.seed' just before calling 'simPopEtas()'.

A long-format parameter table containing par.type and i columns. If this is supplied, the parameter values will not be read from an ext file, and file has no effect. If an ext file is available, it is most likely better to use the file argument.

An optional phi file to write the generated subjects to.

If 'file.phi' exists already, overwrite it? Default is 'FALSE'.

The default is to return data as a data.frame. Pass a function (say 'tibble::as_tibble') in as.fun to convert to something else. If data.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

Deprecated. Use file instead.

Deprecated. Use seed.R instead.

Additional arguments passed to NMdata::NMreadExt().

Name of the argument

argument value

If val.arg is NULL, what should be returned?

What values are allowed

run tolower?

clean white spaces?

single or multiple file or dir paths as strings.

Passed to 'forestSummarize()'

An NMsimRes object (from NMsim).

Not used

The length of the diagonal. Same as number of rows or columns.

an NMsimModTab object

arguments passed to other methods.

an NMsimRes object

arguments passed to other methods.

the character lines to write

The file name path to write to

Passed to 'nameMultipleFiles()'