Package 'nonmemica'

Title: Create and Evaluate NONMEM Models in a Project Context
Description: Systematically creates and modifies NONMEM(R) control streams. Harvests NONMEM output, builds run logs, creates derivative data, generates diagnostics. NONMEM (ICON Development Solutions <https://www.iconplc.com/>) is software for nonlinear mixed effects modeling. See 'package?nonmemica'.
Authors: Tim Bergsma [aut, cre]
Maintainer: Tim Bergsma <[email protected]>
License: GPL-3
Version: 1.0.11
Built: 2024-10-26 03:36:56 UTC
Source: CRAN

Help Index


Check if File Path is Absolute

Description

Checks if file path is absolute.

Usage

absolute(x)

Arguments

x

character (a file path)

Value

logical; TRUE if x starts with / or .: (e.g. C:)


Convert Vector to Best of Numeric or Character

Description

Convert vector to best of numeric or character.

Usage

## Default S3 method:
as.best(x, prefix = "", na.strings = c(".", "NA", ""), ...)

Arguments

x

default

prefix

prefix for viewing numerics

na.strings

strings that should be treated as NA

...

ignored

Details

Converts vector to numeric if doing so creates no new NA; otherwise to character. Number-like vectors that are nevertheless character are prefixed by default to make this explicit when viewing only a few rows.

See Also

Other util: %contains%(), as.best(), enclose(), locf(), padded(), parens(), pool(), runhead(), text2decimal()


Create Bootstrap from Bootstrap

Description

Creates bootstrap from bootstrap.

Usage

## S3 method for class 'bootstrap'
as.bootstrap(x, ...)

Arguments

x

bootstrap

...

ignored

Value

data.frame

See Also

Other as.bootstrap: as.bootstrap(), as.bootstrap.numeric()


Coerce to Half Matrix by Default

Description

Coerces to half matrix. Treats x as halfmatrix, coerces to matrix and takes half.

Usage

## Default S3 method:
as.halfmatrix(x, ...)

Arguments

x

object

...

passed arguments

See Also

Other halfmatrix: as.data.frame.halfmatrix(), as.halfmatrix(), as.halfmatrix.halfmatrix(), as.matrix.halfmatrix(), half(), half.matrix(), is.square(), is.square.matrix(), offdiag(), offdiag.halfmatrix(), ord(), ord.halfmatrix(), ord.matrix(), print.halfmatrix()


Coerce init to init

Description

Coerces init to init

Usage

## S3 method for class 'init'
as.init(x = numeric(0), fixed = FALSE, comment = character(0), ...)

Arguments

x

init

fixed

logical

comment

character

...

passed arguments

Value

init

See Also

Other as.init: as.init(), as.init.numeric()


Coerce list to inits

Description

Coerces list to inits.

Usage

## S3 method for class 'list'
as.inits(x, comment = character(0), ...)

Arguments

x

list

comment

character

...

passed arguments

Value

inits

See Also

Other as.inits: as.inits(), as.inits.numeric()


Coerce Half Matrix to Matrix

Description

Coerces half matrix to matrix.

Usage

## S3 method for class 'halfmatrix'
as.matrix(x, ...)

Arguments

x

object

...

passed arguments

See Also

Other halfmatrix: as.data.frame.halfmatrix(), as.halfmatrix(), as.halfmatrix.default(), as.halfmatrix.halfmatrix(), half(), half.matrix(), is.square(), is.square.matrix(), offdiag(), offdiag.halfmatrix(), ord(), ord.halfmatrix(), ord.matrix(), print.halfmatrix()


Coerce character to model

Description

Coerces chacter to model.

Usage

## S3 method for class 'character'
as.model(
  x,
  pattern = "^\\s*\\$(\\S+)(\\s.*)?$",
  head = "\\1",
  tail = "\\2",
  parse = TRUE,
  ...
)

Arguments

x

character

pattern

pattern to identify record declarations

head

subpattern to identify declaration type

tail

subpattern remaining

parse

whether to convert thetas omegas and sigmas to inits, tables to items, and runrecords to fields

...

ignored

Value

list

See Also

Other as.model: [.model(), [[.model(), as.model(), as.model.numeric(), read.model(), write.model()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.model

Create an xml_document in a Project Context

Description

Creates an xml_document in a project context.

Coerces xml_document to xml_document

Usage

as.xml_document(x, ...)

## S3 method for class 'xml_document'
as.xml_document(x, ...)

Arguments

x

xml_document

...

ignored

Value

xml_document

xml_document

Methods (by class)

  • as.xml_document(xml_document): xml_document method

See Also

xpath

Other xpath: as.xml_document.character(), as.xml_document.numeric(), xpath(), xpath.default(), xpath.xml_document()

Other xpath: as.xml_document.character(), as.xml_document.numeric(), xpath(), xpath.default(), xpath.xml_document()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.xml_document

Create xml_document From Character

Description

Creates an xml_document from character (modelname or filepath).

Usage

## S3 method for class 'character'
as.xml_document(x, strip.namespace = TRUE, ...)

Arguments

x

file path or run name

strip.namespace

whether to strip e.g. nm: from xml elements

...

passed to modelpath()

Value

xml_document

See Also

Other xpath: as.xml_document(), as.xml_document.numeric(), xpath(), xpath.default(), xpath.xml_document()


Extract Comments from Inits

Description

Extracts comments from inits.

Usage

## S3 method for class 'inits'
comments(x, type, prior, ...)

Arguments

x

inits

type

item type: theta, omega, sigma (tables give items not inits)

prior

number of prior items of this type (maybe imporant for numbering)

...

ignored

Value

data.frame

See Also

Other comments: comments(), comments.items(), comments.model()


Extract Comments from Items

Description

Extracts comments from items.

Usage

## S3 method for class 'items'
comments(x, ...)

Arguments

x

items

...

ignored

Value

data.frame

See Also

Other comments: comments(), comments.inits(), comments.model()


Extract Comments from Model

Description

Extracts comments from model.

Usage

## S3 method for class 'model'
comments(
  x,
  fields = c("symbol", "unit", "label"),
  expected = character(0),
  na = NA_character_,
  tables = TRUE,
  ...
)

Arguments

x

model

fields

data items to scavenge from control stream comments

expected

parameters known from NONMEM output

na

string to use for NA values when writing default metafile

tables

whether to include table comments

...

passed arguments

Value

data.frame

See Also

Other comments: comments(), comments.inits(), comments.items()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.model %>% comments

Check Whether Text Contains Pattern

Description

Checks whether text contains pattern.

Usage

contains(pattern, text, ...)

Arguments

pattern

regular expression

text

character vector to check

...

arguments to methods

Value

logical

See Also

%contains%


Identify the Datafile for a Model

Description

Identifies the datafile used by a model. Expresses it relative to current working directory.

Usage

## S3 method for class 'character'
datafile(x, ...)

Arguments

x

the model name or path to a control stream

...

ext can be passed to modelfile, etc.

Value

character

See Also

Other path: datafile(), datafile.numeric(), modeldir(), modelfile(), modelpath(), modelpath.character(), modelpath.numeric(), psn_options(), specfile(), specfile.character(), specfile.numeric()

Examples

library(spec)
source <- system.file(package = 'nonmemica','project')
target <- tempdir()
target <- gsub('\\\\','/',target) # for windows
file.copy(source,target,recursive = TRUE)
project <- file.path(target,'project','model')
options(project = project)
library(magrittr)
1001 %>% datafile
datafile(1001) %matches% specfile(1001)
1001 %>% specfile
1001 %>% specfile %>% read.spec

Harvest Model Item Definitions

Description

Havests model item definitions.

Create Item Definitions from Model Name

Usage

definitions(x, ...)

## S3 method for class 'character'
definitions(
  x,
  verbose = FALSE,
  ctlfile = modelfile(x, ...),
  metafile = modelpath(x, "def", ...),
  fields = getOption("fields", default = c("symbol", "label", "unit")),
  read = length(metafile) == 1,
  write = FALSE,
  ...
)

Arguments

x

object of dispatch

...

arguments to methods

verbose

set FALSE to suppress messages

ctlfile

path to control stream (pass length-zero argument to ignore)

metafile

path to definitions file (pass length-zero argument to ignore)

fields

metadata fields to read from control stream if no metafile

read

whether to read the definitions file

write

whether to write the definitions file

Details

x can be numeric or character model name, assuming project is identified by argument or option.

Creates item definitions from a model name. Scavenges definitions optionally from the control stream and optionally from the definitions file. Optionally writes the result to the definitions file. Always returns a data.frame with at least the column 'item' but possibly no rows.

Value

object of class definitions, or path to metafile if write = TRUE.

Methods (by class)

  • definitions(character): character method

See Also

definitions.character

as.xml_document.character

as.bootstrap.character

as.model.character

Other definitions: definitions.definitions(), definitions.numeric()

Other definitions: definitions.definitions(), definitions.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% definitions

Create Model Item Definitions from definitions

Description

Creates a model item definitions from a definitions object.

Usage

## S3 method for class 'definitions'
definitions(x, ...)

Arguments

x

definitions

...

ignored

Details

Just returns the object unmodified.

See Also

Other definitions: definitions(), definitions.numeric()


Identify Model Dependencies

Description

Identify those models in the lineage of models in x.

Usage

## Default S3 method:
depends(x, ...)

Arguments

x

object

...

passed arguments

Value

character

See Also

Other depends: depends()


Get Errors for Character

Description

Gets model asymptotic standard errors in canonical order, treating character as model names. See parameters for a less formal interface.

Usage

## S3 method for class 'character'
errors(
  x,
  xmlfile = modelpath(x, ext = "xml", ...),
  strip.namespace = TRUE,
  digits = 3,
  ...
)

Arguments

x

character (modelname)

xmlfile

path to xml file

strip.namespace

whether to strip e.g. nm: from xml elements for easier xpath syntax

digits

passed to signif

...

dots

Value

numeric

See Also

nms_canonical errors

Other errors: errors(), errors.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% errors

Get Estimates for Character

Description

Gets model parameter estimates in canonical order, treating character as model names. See parameters for a less formal interface.

Usage

## S3 method for class 'character'
estimates(
  x,
  xmlfile = modelpath(x, ext = "xml", ...),
  strip.namespace = TRUE,
  digits = 3,
  ...
)

Arguments

x

character (modelname)

xmlfile

path to xml file

strip.namespace

whether to strip e.g. nm: from xml elements for easier xpath syntax

digits

passed to signif

...

dots

Value

numeric

See Also

nms_canonical errors

Other estimates: estimates(), estimates.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% estimates

Check if init is fixed

Description

Checks if init is fixed.

Usage

## S3 method for class 'init'
fixed(x, ...)

Arguments

x

init

...

ignored

Value

logical

See Also

Other fixed: fixed(), fixed.model(), fixed<-(), fixed<-.init(), fixed<-.inits(), fixed<-.model()


Check If Model is Fixed

Description

Checks if model is fixed. Returns a logical vector with element for each init, in canonical order.

Usage

## S3 method for class 'model'
fixed(x, ...)

Arguments

x

inits

...

ignored

Value

logical

See Also

Other fixed: fixed(), fixed.init(), fixed<-(), fixed<-.init(), fixed<-.inits(), fixed<-.model()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.model %>% fixed

Generalize a Nonmissing Value

Description

#Generalize a nonmissing value. If there is only one such among zero or more NA, impute that value for all NA.

Usage

generalize(x, ...)

Arguments

x

vector

...

ignored

See Also

Other superset: ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()


Extract Index for Ignored Records

Description

Extracts index for ignored records, given a NONMEM control stream.

Usage

ignored(
  x,
  read.input = list(read.csv, header = TRUE, as.is = TRUE),
  ext = getOption("modex", "ctl"),
  project = getOption("project", getwd()),
  nested = getOption("nested", TRUE),
  ...
)

Arguments

x

length-one character: a model name

read.input

list of arguments representing a methodology for acquiring the data of interest: the first argument is not named and will be passed to match.fun(); the other arguments will be passed to the result, and must include an argument named 'header'.

ext

model file extension, e.g. 'mod' or 'ctl'

project

project directory (can be expression)

nested

whether model files are nested in eponymous directories

...

passed to modelfile and link{datafile}

Value

logical

See Also

Other superset: generalize(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()


Get Model Initial Estimates

Description

Gets model initial estimates.

Usage

## S3 method for class 'model'
initial(x, ...)

Arguments

x

model

...

dots

See Also

Other initial: initial(), initial<-(), initial<-.model()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.model %>% initial

Set Upper Bounds for Model Initial Estimates

Description

Sets upper bounds for model initial estimates.

Usage

## S3 replacement method for class 'model'
initial(x) <- value

Arguments

x

model

value

numeric

See Also

Other initial: initial(), initial.model(), initial<-()


Modify a Model

Description

Makes a copy of a model in a corresponding directory. Problem statement is updated to reflect that the model is LIKE the reference model BUT different in some fundamental way.

Usage

likebut(
  x,
  but = "better",
  y = NULL,
  project = getOption("project", getwd()),
  nested = getOption("nested", TRUE),
  overwrite = FALSE,
  ext = getOption("modex", "ctl"),
  include = "\\.def$",
  update = FALSE,
  ...
)

Arguments

x

a model name, presumably interpretable as numeric

but

a short description of the characteristic difference from x

y

optional name for model to be created, auto-incremented by default

project

project directory (can be expression)

nested

model files nested in run-specific directories

overwrite

whether to overwrite y if it exists

ext

extension for the model file

include

regular expressions for files to copy to new directory

update

use final estimates of x as initial estimates of y

...

passed arguments, including PsN runrecord elements (experimental)

Value

the value of y

See Also

runlog.character

Examples

# Create a working project.
source <- system.file(package = 'nonmemica','project')
target <- tempdir()
target <- gsub('\\\\','/',target) # for windows
source
target
file.copy(source,target,recursive = TRUE)
project <- file.path(target,'project','model')

# Point project option at working project
options(project = project)
library(magrittr)

# Derive models.
1001 %>% likebut('revised',y = 1002, overwrite=TRUE )

# At this point, edit 1002.ctl to match whatever 'revised' means.
# Then run it with NONMEM.

Get Lower Bounds for Model Initial Estimates

Description

Gets lower bounds for model initial estimates.

Usage

## S3 method for class 'model'
lower(x, ...)

Arguments

x

model

...

dots

See Also

Other lower: lower(), lower<-(), lower<-.model()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.model %>% lower

Set Lower Bounds for Model Initial Estimates

Description

Sets lower bounds for model initial estimates.

Usage

## S3 replacement method for class 'model'
lower(x) <- value

Arguments

x

model

value

numeric

See Also

Other lower: lower(), lower.model(), lower<-()


Get Metadata for Character

Description

Gets metadata for character, treating it as a model name. Blends metadata from specfile with metadata from control stream, removing both exact duplicates as well as redefined values (with warning).

Usage

## S3 method for class 'character'
meta(x, simplify = TRUE, ...)

Arguments

x

object

simplify

logical: remove range information from guide text

...

passed arguments

Value

data.frame

See Also

Other superset: generalize(), ignored(), meta(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% meta

Metaplot Character, Standard Evaluation

Description

Plots character by treating as model name. A dataset is constructed by combining the model input with a the model output and calling metaplot with the result.

Usage

metaplot_character(x, groups, meta = NULL, subset, var, ...)

Arguments

x

object

groups

columns by which to group the dataset

meta

metadata; meta(x) by default

subset

a condition for filtering data

var

variables to plot

...

passed arguments

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()


Metaplot Character

Description

Plots character by treating as model name. A dataset is constructed by combining the meta version of the model input with a meta version of the model output and calling metaplot with the result.

Usage

## S3 method for class 'character'
metaplot(x, ..., groups, meta = match.fun("meta")(x), subset)

Arguments

x

object

...

unquoted names of variables to plot, or other named arguments (passed)

groups

columns by which to group the dataset

meta

metadata; meta(x) by default

subset

a condition for filtering data

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()

Examples

library(magrittr)
library(metaplot)
options(project = system.file('project/model',package='nonmemica'))
## Not run: 
1001 %>% metaplot(
 CWRESI, TAD, SEX, 
 groups = c('ID','TIME'), 
 subset = 'MDV == 0',
 yref = 0, 
 ysmooth = TRUE
)

## End(Not run)

Retrieve Model Outputs with Metadata

Description

Retrieves model outputs with metadata.

Usage

metasuperset(
  x,
  groups,
  meta = match.fun("meta")(x, ...),
  subset = getOption("metasuperset_subset", NULL),
  ...
)

Arguments

x

model name

groups

vector of key column names in superset, e.g. USUBJID, TIME

meta

metadata with column 'item' and possibly attributes such as 'label' and 'guide'

subset

length-one character: a condition for filtering results, e.g. 'EVID == 0'

...

passed arguments

Value

data.frame

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% metasuperset(c('ID','TIME')) %>% head

Identify the Directory for a Model

Description

Identifies the directory used by a model.

Usage

modeldir(x, ext, ...)

Arguments

x

the model name

ext

model file extension

...

passed arguments

Value

character

See Also

Other path: datafile(), datafile.character(), datafile.numeric(), modelfile(), modelpath(), modelpath.character(), modelpath.numeric(), psn_options(), specfile(), specfile.character(), specfile.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% modeldir

Identify the Modelfile for a Model

Description

Identifies the modelfile used by a model.

Usage

modelfile(x, ext = getOption("modex", "ctl"), ...)

Arguments

x

the model name

ext

model file extension

...

passed arguments

Value

character

See Also

Other path: datafile(), datafile.character(), datafile.numeric(), modeldir(), modelpath(), modelpath.character(), modelpath.numeric(), psn_options(), specfile(), specfile.character(), specfile.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% modelfile('xml')

Resolve A Path to a Model-related File

Description

Resolves a path to a model-related file.

Usage

modelpath(x, ...)

Arguments

x

object

...

passed arguments

Value

character

See Also

Other path: datafile(), datafile.character(), datafile.numeric(), modeldir(), modelfile(), modelpath.character(), modelpath.numeric(), psn_options(), specfile(), specfile.character(), specfile.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% modelpath

Resolve A Path to a Model-related File for Character

Description

Resolves a path to a model-related file, treating x as a model name. By default (ext is NULL) the run directory is returned. As of version 0.9.2, nested can be a function of ext and ... That returns logical.

Usage

## S3 method for class 'character'
modelpath(
  x,
  ext = NULL,
  project = getOption("project", getwd()),
  nested = getOption("nested", TRUE),
  ...
)

Arguments

x

object

ext

file extension, no leading dot

project

project directory (can be expression)

nested

whether model files are nested in eponymous directories

...

passed arguments

Value

character

See Also

Other path: datafile(), datafile.character(), datafile.numeric(), modeldir(), modelfile(), modelpath(), modelpath.numeric(), psn_options(), specfile(), specfile.character(), specfile.numeric()


Calculate Number of Inputs

Description

Calculates number of inputs.

Usage

ninput(x, ...)

Arguments

x

object

...

passed arguments

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()


Calculate Number of Inputs for Character

Description

Calculates number of inputs for character by treating as a model name.

Usage

## S3 method for class 'character'
ninput(x, ...)

Arguments

x

character

...

passed arguments

Value

integer

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()


Calculate Number of Inputs for Numeric

Description

Calculates number of inputs for numeric by coercing to character.

Usage

## S3 method for class 'numeric'
ninput(x, ...)

Arguments

x

numeric

...

passed arguments

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()


Generate Canonical Names for Character

Description

Generates canonical names for character by converting to parsed model.

Usage

## S3 method for class 'character'
nms_canonical(x, ...)

Arguments

x

object of dispatch

...

passed arguments

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% nms_canonical

Generate Canonical Names for Model

Description

Generates canonical names for a NONMEM control stream object. Canonical names indicate all and only the declared model parameters in lower-case conventional order (theta, omega row-major, sigma) with underscores and two-digit (or more) indices. E.g. theta_01, theta_02, omega_01_01, omega_02_01, omega_02_02, omega_01_01.

Usage

## S3 method for class 'model'
nms_canonical(x, ...)

Arguments

x

a model designator

...

passed arguments

Value

nms_canonical (character)

See Also

as.model

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()


Convert NONMEM Parameter Names to Canonical

Description

Converts nms_nonmem to nms_canonical.

Usage

## S3 method for class 'nms_nonmem'
nms_canonical(x, ...)

Arguments

x

nms_nonmem

...

ignored

Value

nms_canonical

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()


Generate NONMEM Names for Character

Description

Generates NONMEM names for numeric by converting to parsed model.

Usage

## S3 method for class 'character'
nms_nonmem(x, ...)

Arguments

x

object of dispatch

...

passed arguments

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% nms_nonmem

Generate NONMEM Names for Model

Description

Generates NONMEM names for parameters declared in a NONMEM control stream object.

Usage

## S3 method for class 'model'
nms_nonmem(x, ...)

Arguments

x

a model designator

...

passed arguments

Value

nms_nonmem (character)

See Also

as.model

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.model %>% nms_nonmem

Convert Canonical Parameter Names to NONMEM

Description

Converts nms_canonical to nms_nonmem.

Usage

## S3 method for class 'nms_canonical'
nms_nonmem(x, ...)

Arguments

x

nms_canonical

...

ignored

Value

nms_nonmem

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()

Examples

# example code

Convert pmxTools Names to NONMEM

Description

Converts nms_pmx to nms_nonmem. I.e., THETA1 stays THETA1, but OM1,1 becomes OMEGA(1,1).

Usage

## S3 method for class 'nms_pmx'
nms_nonmem(x, ...)

Arguments

x

nms_pmx

...

ignored

Value

nms_nonmem (character)

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()

Other nm: nms_canonical.nms_pmx(), nms_pmx.nms_nonmem()

Examples

library(magrittr)
c(
   'THETA1',
   'OM1,1',
   'OM1,2',
   'SG1,1',
   'SG1,2'
) %>%
as_nms_pmx %>%
nms_canonical

Convert Canonical Names to pmxTools

Description

Converts nms_canonical to nms_pmx. I.e., theta_01 becomes THETA1, and omega_01_01 becomes OM1,1.

Usage

## S3 method for class 'nms_canonical'
nms_pmx(x, ...)

Arguments

x

nms_canonical

...

ignored

Value

nms_pmx (character)

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()

Examples

library(magrittr)
c(
   'theta_15',
   'omega_01_01',
   'omega_01_02',
   'sigma_01_01',
   'sigma_02_01'
) %>%
as_nms_canonical %>%
nms_pmx

Convert NONMEM Names to pmxTools

Description

Converts nms_nonmem to nms_pmx. I.e., THETA1 stays THETA1, but OMEGA(1,1) becomes OM1,1.

Usage

## S3 method for class 'nms_nonmem'
nms_pmx(x, ...)

Arguments

x

nms_pmx

...

ignored

Value

nms_nonmem (character)

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_psn(), nms_psn.character(), nms_psn.model(), nms_psn.numeric()

Other nm: nms_canonical.nms_pmx(), nms_nonmem.nms_pmx()

Examples

library(magrittr)
c(
   'THETA1',
   'OMEGA(1,1)',
   'OMEGA(1,2)',
   'SIGMA(1,1)',
   'SIGMA(1,2)'
) %>%
as_nms_pmx %>%
nms_canonical

Generate PsN-style Names for Character

Description

Generates PsN-style names for numeric by converting to parsed model.

Usage

## S3 method for class 'character'
nms_psn(x, ...)

Arguments

x

object of dispatch

...

passed arguments

See Also

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.model(), nms_psn.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% nms_psn

Generate PsN-style Names for Model

Description

Generates PsN-style names for parameters declared in a NONMEM control stream object. PsN uses NONMEM-style names, substituting a comment, if any: everything after the first semicolon, up to the second semicolon if present, without leading/trailing spaces/tabs.

Usage

## S3 method for class 'model'
nms_psn(x, ...)

Arguments

x

a model designator

...

passed arguments

Value

nms_psn (character)

See Also

as.model

Other nms: as_nms_canonical(), as_nms_nonmem(), as_nms_pmx(), as_nms_psn(), nms_canonical(), nms_canonical.character(), nms_canonical.model(), nms_canonical.nms_nonmem(), nms_canonical.nms_pmx(), nms_canonical.numeric(), nms_nonmem(), nms_nonmem.character(), nms_nonmem.model(), nms_nonmem.nms_canonical(), nms_nonmem.nms_pmx(), nms_nonmem.numeric(), nms_pmx(), nms_pmx.nms_canonical(), nms_pmx.nms_nonmem(), nms_psn(), nms_psn.character(), nms_psn.numeric()


Create and Evaluate NONMEM Models in a Project Context

Description

Nonmemica (emphasis like 'America') creates and evaluates NONMEM models in a project context.

Details

NONMEM (ICON Development Solutions) is software for nonlinear mixed effects modeling. The fundamental interface is a text file (control stream, typ. *.mod or *.ctl) that specifies model input, structure, and output. There are many add-on interfaces for NONMEM (see references for a few examples). However, much day-to-day modeling, even for R users, involves substantial manual interventions.

Nonmemica streamlines interactions with NONMEM. It adopts some established conventions and techniques (e.g. from PsN and metrumrg), but introduces others that may be useful. Principally, it parses existing control streams for systematic analysis and alteration. Relatively simple, single-problem control streams are supported; see the example.

Of course, NONMEM itself is licensed software that must be installed independently. Nonmemica is largely indifferent to how NONMEM is installed or invoked. However, several features depend on the *.xml output that NONMEM creates; make sure it is available. Also, the best-supported directory structure is that which has numbers for model names, with all model-specific files in eponymous subdirectories of a "project" directory. An example is given below.

Nonmemica adopts three control stream encoding conventions that merit special mention. First, the problem statement is encoded in the form //like/x//but/y// where x is a reference model name and y is a feature difference from the reference model (see likebut() ). This allows any given model to be described by chaining together its legacy of features (use runlog(depenencies = TRUE, ...) ), which generally works better than trying to describe it exhaustively in the model name. As of version 0.9.2, experimental support is available for natural-language problem statements of the form "like run1001 but fixed additive error".

Second, Nonmemica only needs a single output table ($TABLE record). Be sure to use ONEHEADER but avoid FIRSTONLY. Nonmemica will integrate model inputs and outputs, regardless of table counts, into one data.frame (see superset() ).

Third, Nonmemica supports integrated metadata. With respect to model inputs, use package spec to store column metadata in a companion file (a data specification, e.g. *.spec). Keep the data file and data specification in a central location, not copied to the model directory. For model outputs (tabled items) supply column metadata directly in the control stream (or a *.def file; see example and help).

Nonmemica supports three global options: 'project' (default getwd() ) is the parent directory of model-specific files or directories; 'nested' (default TRUE) tells whether model-specific files are nested within eponymous directories; 'modex' (default 'ctl') gives the file extension for control streams. In many cases you can pass these options to the relevant functions; but since they likely won't change for the scope of a given project, it saves effort to set them as global options (if they differ from the defaults) using e.g. options(project=).

Numbers make good names for models because it is never hard for you or the software to think of a new one. That said, model names are typically processed as character in Nonmemica. There are many generic functions with both numeric and character methods that simply assume the (length-one) argument you supply is a model name.

Author(s)

Maintainer: Tim Bergsma [email protected]

References

NONMEM

Icon

PsN

Xpose

Wings for NONMEM

metrumrg

Examples

# Create a working project.
source <- system.file(package = 'nonmemica','project')
target <- tempdir()
target <- gsub('\\\\','/',target) # for windows
source
target
file.copy(source,target,recursive = TRUE)
project <- file.path(target,'project','model')

# Point project option at working project
options(project = project)

# Load some packages
library(magrittr)
library(metaplot)
library(wrangle)
library(spec)
library(dplyr,warn.conflicts = FALSE)

# Identify features of a model.
1001 %>% modelpath
1001 %>% modeldir
1001 %>% modelfile
1001 %>% modelpath('xml')
1001 %>% datafile
datafile(1001) %matches% specfile(1001)
1001 %>% specfile
1001 %>% specfile %>% read.spec
1001 %>% as.model
1001 %>% as.model %>% comments
1001 %>% definitions
1001 %>% runlog(TRUE)
1001 %>% runlog
1001 %>% partab
1001 %>% num_parameters
1001 %>% nms_canonical
1001 %>% nms_psn
1001 %>% nms_nonmem
1001 %>% parameters
1001 %>% errors
1001 %>% as.model %>% initial
1001 %>% as.model %>% lower
1001 %>% as.model %>% upper
1001 %>% as.model %>% fixed
1001 %>% meta %>% class
1001 %>% meta

# Derive datasets.
1001 %>% superset %>% head
1001 %>% superset %>% filter(VISIBLE == 1) %>% group_by(ID,TIME) %>% status
1001 %>% metasuperset(c('ID','TIME')) %>% head
1001 %>% metasuperset(c('ID','TIME')) %>% sapply(attr,'label')

# Make diagnostic plots.
1001 %>% metaplot(
 CWRESI, TAD, SEX, 
 groups = c('ID','TIME'), 
 subset = 'MDV == 0',
 yref=0, 
 ysmooth = TRUE
)
1001 %>% metaplot(
 ETA1, SEX, 
 ref = 0,
 groups = c('ID','TIME'),
 subset = 'MDV == 0'
)
1001 %>% metaplot(
 SEX, ETA1, 
 ref = 0,
 groups = c('ID','TIME'),
 subset = 'MDV == 0'
)
1001 %>% metaplot(
 ETA1, ETA2, ETA3,
 groups = c('ID','TIME'),
 subset = 'MDV == 0'
)

# Derive models.
1001 %>% likebut('revised',y = 1002, overwrite=TRUE )
# At this point, edit 1002.ctl to match whatever 'revised' means.
# Then run it with NONMEM and post-process results as above.

# Make ten new models with slightly different initial estimates.
1001 %>% tweak

Isolate Off-diagonal of Half Matrix

Description

Isolates off-diagonal of halfmatrix.

Usage

## S3 method for class 'halfmatrix'
offdiag(x, ...)

Arguments

x

object

...

passed arguments

See Also

Other halfmatrix: as.data.frame.halfmatrix(), as.halfmatrix(), as.halfmatrix.default(), as.halfmatrix.halfmatrix(), as.matrix.halfmatrix(), half(), half.matrix(), is.square(), is.square.matrix(), offdiag(), ord(), ord.halfmatrix(), ord.matrix(), print.halfmatrix()


Get Parameters for Character

Description

Gets parameters, treating character as model names. If x is length one, slightly more details are returned such as datafile, reference model, and feature. Otherwise results are bound together, one model per column. See estimates and errors for a more formal interface to model estimates and asymptotic standard errors.

Usage

## S3 method for class 'character'
parameters(x, simplify = FALSE, ...)

Arguments

x

object

simplify

if x is length one and simplify is TRUE, return a named vector

...

passed arguments

Value

data.frame

See Also

Other parameters: parameters(), parameters.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% parameters

Create Parameter Table

Description

Creates a parameter table.

Creates a model parameter table from a partab object.

Usage

partab(x, ...)

## S3 method for class 'partab'
partab(x, ...)

Arguments

x

partab

...

ignored

Details

x can be numeric or character model name, assuming project is identified by argument or option.

Just returns the object unmodified.

Methods (by class)

  • partab(partab): partab method

See Also

partab.character

Other partab: partab.character(), partab.numeric()

Other partab: partab.character(), partab.numeric()


Create a Parameter Table from Model Name

Description

Creates a parameter table from a model name. Pass the project argument or set the project option.

Usage

## S3 method for class 'character'
partab(
  x,
  verbose = FALSE,
  lo = "5",
  hi = "95",
  metafile = modelpath(x, "def", ...),
  xmlfile = modelpath(x, "xml", ...),
  ctlfile = modelfile(x, ...),
  bootcsv,
  strip.namespace = TRUE,
  skip = 28,
  check.names = FALSE,
  digits = 3,
  ci = TRUE,
  open = "(",
  close = ")",
  sep = ", ",
  format = TRUE,
  fields = getOption("fields", default = c("symbol", "label", "unit")),
  relative = TRUE,
  percent = relative,
  nonzero = TRUE,
  shrinkage = FALSE,
  correlation = FALSE,
  ...
)

Arguments

x

a model name (numeric or character)

verbose

set FALSE to suppress messages

lo

the PsN bootstrap lower confidence limit (%)

hi

the PsN bootstrap upper confidence limit (%)

metafile

optional metadata for parameter table (see also: fields)

xmlfile

path to xml file

ctlfile

path to control stream

bootcsv

path to PsN bootstrap_results.csv

strip.namespace

whether to strip e.g. nm: from xml elements for easier xpath syntax

skip

number of lines to skip in bootstrap_results.csv

check.names

passed to bootstrap reader

digits

limits numerics to significant digits (use NULL to suppress)

ci

combine bootstrap lo and hi into an enclosed interval

open

first character for bootstrap interval

close

last character for bootstrap interval

sep

separator for bootstrap interval

format

format numerics as character

fields

metadata fields to read from control stream. See details.

relative

transform standard errors to relative standard errors: rse replaces se

percent

if relative is true, express as percent (else ignore): prse replaces se

nonzero

limit random effects to those with nonzero estimates

shrinkage

whether to include percent shrinkage on random effects

correlation

whether to include correlation of random effects (as percent if percent is true)

...

passed to other functions

Details

Normally you can just call the generic. Suitable defaults are supplied, but much customization is supported by means of arguments documented here and in called functions.

Metadata can be added to the parameter table two ways: as markup in the control stream, and as a *.def file in the model directory. See vignette('parameter-table') for details.

Value

object of class partab, data.frame

See Also

as.xml_document.character

as.bootstrap.character

as.model.character

as.csv

Other partab: partab(), partab.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% partab
1001 %>% partab(shrinkage = TRUE, correlation = TRUE)

Identify the Model Problem Statement for Character

Description

Identifies the model problem statement for character (model name).

Usage

## S3 method for class 'character'
problem(x, ...)

Arguments

x

object

...

passed arguments

Value

character

See Also

Other problem: as.problem(), problem(), problem.numeric(), problem_()


PsN Model File is Nested

Description

Check whether a particular file extension corresponds to a file that is nested within a subdirectory using default PsN conventions.

Usage

psn_nested(x, ...)

Arguments

x

character, a file extension, without dot.

...

ignored

Value

logical

Examples

psn_nested('mod')

Set PsN Options

Description

Sets PsN-style directory and control stream options. Supports control streams with semicolon-delimited metadata including symbol, unit, transform, and label. Expects model files to be found in nested directory, except for *.mod and *.lst.

Usage

psn_options(
  project = "NONMEM",
  modex = "mod",
  fields = c("symbol", "unit", "transform", "label"),
  nested = psn_nested,
  ...
)

Arguments

project

character, path to project directory

modex

character, extension for model control stream (no dot)

fields

character

nested

logical, or function of file extension returning logical

...

ignored

Value

used for side-effects (sets options 'fields' and 'nested')

See Also

Other path: datafile(), datafile.character(), datafile.numeric(), modeldir(), modelfile(), modelpath(), modelpath.character(), modelpath.numeric(), specfile(), specfile.character(), specfile.numeric()

Examples

## Not run: 
psn_options()

## End(Not run)

Relativize a Path

Description

Relativizes a path.

Usage

relativizePath(x, dir = getwd(), sep = "/", ...)

Arguments

x

a file path

dir

a reference directory

sep

path separator

...

ignored arguments

Details

x and dir are first normalized, then x is expressed relative to dir. If x and dir are on different drives (i.e. C:/ D:/) x is returned as an absolute path.


Resolve File Path

Description

Resolves a file path. Returns the path if absolute. If relative, concatenates the directory and file.

Usage

resolve(file, dir)

Arguments

file

path to a file

dir

reference directory for a relative file path

Value

character


Translate Parameter Names

Description

Translate among various idioms for expressing parameter names

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))

# we generate some nonmem parameter names in nonmem format
1001 %>% nms_nonmem -> nonmem
nonmem

# from these we generate canonical and pmxTools equivalents
canonical <- nms_canonical(nonmem)
pmxtools <- nms_pmx(nonmem)
canonical
pmxtools

# We demonstrate equivalence
stopifnot(identical(nonmem, nms_nonmem(canonical)))
stopifnot(identical(nonmem, nms_nonmem(pmxtools)))
stopifnot(identical(canonical, nms_canonical(nonmem)))
stopifnot(identical(canonical, nms_canonical(pmxtools)))
stopifnot(identical(pmxtools, nms_pmx(nonmem)))
stopifnot(identical(pmxtools, nms_pmx(canonical)))

# on-the-fly conversions
nonmem %>% class
nonmem %>% nms_pmx
nonmem %>% nms_canonical
nonmem %>% nms_canonical %>% nms_pmx
nonmem %>% nms_canonical %>% nms_pmx %>% nms_nonmem

# comparison
data.frame(
 can = I(canonical),
 non = I(nonmem),
 pmx = I(pmxtools),
 psn = I(nms_psn(1001))
)

Create a Runlog for Character

Description

Creates a Runlog for character by treating x as modelname(s).

Usage

## S3 method for class 'character'
runlog(x, dependencies = FALSE, digits = 3, places = 0, ...)

Arguments

x

object

dependencies

whether to log runs in lineage(s) as well

digits

significance for parameters

places

rounding for objective function

...

passed arguments

Value

data.frame

See Also

likebut

Other runlog: runlog(), runlog.numeric()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
# likebut(2001,'2 cmt', 2002)              # edit manually, then ...
# likebut(2002,'add. err.', 2003)          # edit manually, then ...
# likebut(2003,'allo. WT on CL',2004)      # edit manually, then ...
# likebut(2004,'estimate allometry', 2005) # edit manually, then ...
# likebut(2005,'SEX on CL', 2006)          # edit manually, then ...
# likebut(2006,'full block omega', 2007)   # edit manually, then run all
2007 %>% runlog(dependencies = TRUE)

Join Data Safely

Description

Joins data safely. Generic, with method for data.frame.

Usage

safe_join(x, ...)

Arguments

x

object of dispatch

...

arguments to methods

See Also

safe_join.data.frame

Other safe_join: safe_join.data.frame()


Join Data Frames Safely

Description

Joins data frames safely. I.e., a left join that cannot alter row order or number. Supports the case where you only intend to augment existing rows with additional columns and are expecting singular matches. Gives an error if row order or number would have been altered by a left join.

Usage

## S3 method for class 'data.frame'
safe_join(x, y, ...)

Arguments

x

data.frame

y

data.frame

...

passed to dplyr::left_join

See Also

Other safe_join: safe_join()

Examples

library(magrittr)
x <- data.frame(code = c('a','b','c'), value = c(1:3))
y <- data.frame(code = c('a','b','c'), roman = c('I','II','III'))
x %>% safe_join(y)
try(
x %>% safe_join(rbind(y,y))
)

Move the Columns of a Data Frame Relative to Each Other

Description

Move the columns of a data.frame relative to each other.

Usage

shuffle(x, who, after = NA, ...)

Arguments

x

data.frame

who

a character vector of column names to move, or a logical vector of length names(x), or a vector of indices

after

column after which to put who: may be character, integer, NA, or NULL

...

ignored

Value

data.frame

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()


Identify the Data Specification File for a Model

Description

Identifies the data specification file associated with the datafile used by a model. Locates the datafile specified in the control stream, and substitutes a different extension.

Usage

## S3 method for class 'character'
specfile(x, find = "\\.csv$", use = ".spec", ...)

Arguments

x

the model name

find

file extension to replace

use

file extension to use

...

pass ext over-ride default file extension in datafile()

Value

character

See Also

datafile

Other path: datafile(), datafile.character(), datafile.numeric(), modeldir(), modelfile(), modelpath(), modelpath.character(), modelpath.numeric(), psn_options(), specfile(), specfile.numeric()

Examples

library(spec)
source <- system.file(package = 'nonmemica','project')
target <- tempdir()
target <- gsub('\\\\','/',target) # for windows
file.copy(source,target,recursive = TRUE)
project <- file.path(target,'project','model')
options(project = project)
library(magrittr)
1001 %>% datafile
datafile(1001) %matches% specfile(1001)
1001 %>% specfile
1001 %>% specfile %>% read.spec

Coerce to Superset from Character

Description

Coerces to superset from character, treating x as a model name.

Usage

## S3 method for class 'character'
superset(
  x,
  read.input = list(read.csv, header = TRUE, as.is = TRUE),
  read.output = list(read.table, header = TRUE, as.is = TRUE, skip = 1, comment.char =
    "", check.names = FALSE, na.strings = c("", "\\s", ".", "NA")),
  include = character(0),
  exclude = character(0),
  rename = NULL,
  digits = 5,
  visible = "VISIBLE",
  after = NULL,
  groups = character(0),
  imputation = generalize,
  ...
)

Arguments

x

object

read.input

a methodology for acquiring the input

read.output

a methodology for acquiring the output

include

column names in output to consider adding

exclude

column names in output to reject

rename

logical: whether to keep and rename columns with re-used names

digits

significant digits for assessing informativeness when exclusive=NULL

visible

a name for the flag column indicating visibility

after

place new columns after this column; at end by default (NULL); TRUE places them after last model-visible column (see input statement)

groups

character vector of groupings within which any imputations will be performed

imputation

a list of functions (or arguments to match.fun()) to perform imputations within cells defined by groups: e.g. generalize, forbak, etc (to be tried in succession for new columns only).

...

passed arguments

Details

Given a model name, (project passed or set as global option) superset() figures out the run directory and location of a NONMEM control stream. It reads the control stream to identify the run-time location of input and output files, as well as the "ignore" (and/or "accept") criteria that relate extent of input records to extent of output records. 'read.input' and 'read.output' are lists consisting of functions and arguments appropriate for reading input and output file formats, respectively. The ignore criteria will be reconstructed per row so that output can be mapped unambiguously to input. A column named VISIBLE is bound to the input data, showing 1 where a record was visible to NONMEM, and 0 otherwise. During integration, naming convention of the input is retained, and output column names are mapped by position, using the control stream input criteria. Output tables are restored to input dimensions using the "ignore" criteria, then checked for length: currently, superset ignores output tables having fewer rows than the input, as well as output tables whose row count is not a multiple of input row count. Output tables may contain versions of input columns. Disposition depends on the values of include, exclude, and rename. If include has length, other columns are excluded. Then, if exclude has length, these columns are excluded. Then, if rename is FALSE all remaining columns with re-used names will be dropped. If TRUE, such columns will be renamed (*.n, where n is table number). If NULL, only informative columns will be retained and renamed. A column is informative if any element is informative. An element is informative if it is newly generated (not NA and not zero, but original is NA) or if it is an alteration (non-NA, and different from non-NA original). If the column pair can be interpreted as numeric, "different" is determined using only the first digits digits. Only the first instance of any column among successive output tables is retained. In the control stream, avoid use of FIRSTONLY, as this alters the number of rows.

Value

superset: a data.frame where row count is a multiple of (typically equal to) input row count.

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.numeric(), superspec(), superspec.character(), superspec.numeric()

Examples

library(magrittr)
library(dplyr)
library(wrangle)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% superset %>% head
1001 %>% superset %>% filter(VISIBLE == 1) %>% group_by(ID,TIME) %>% status
1001 %>% ignored %>% table

Create Specification for Model Inputs and Outputs

Description

Create a specification for the result of superset().

Usage

superspec(x, ...)

Arguments

x

object

...

passed arguments

See Also

superspec.character

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec.character(), superspec.numeric()


Create Specification for Model Inputs and Outputs From Character

Description

Create a specification for the result of superset() from character by treating as a model name. By default, gives a spec template for superset(x). Tries to supplement with labels and units from parent specification, if it exists. Tries to supplement with any additional labels and units in definitions(x). Defers to actual data if provided. Specify exclusive, visible, and after as for superset.

Usage

## S3 method for class 'character'
superspec(
  x,
  include = character(0),
  exclude = character(0),
  rename = NULL,
  visible = "VISIBLE",
  after = NULL,
  data = NULL,
  ...
)

Arguments

x

character

include

column names in output to consider adding

exclude

column names in output to reject

rename

logical: whether to keep and rename columns with re-used names

visible

a name for the flag column indicating visibility

after

place new columns after this column; at end by default (NULL); TRUE places them after

data

an alternative dataset on which to model the specification

...

passed arguments

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.numeric()


Create Specification for Model Inputs and Outputs From Numeric

Description

Create a specification for the result of superset() from numeric by coercing to character.

Usage

## S3 method for class 'numeric'
superspec(x, ...)

Arguments

x

numeric

...

passed arguments

See Also

Other superset: generalize(), ignored(), meta(), meta.character(), meta.numeric(), metaplot.character(), metaplot.numeric(), metaplot_character(), metasuperset(), ninput(), ninput.character(), ninput.numeric(), shuffle(), superset(), superset.character(), superset.numeric(), superspec(), superspec.character()


Calculate Time Since Most Recent Dose

Description

Calculate time since most recent dose. Considers ADDL, but may not work with simultaneous dose records.

Usage

tad(
  x,
  dose = rep(FALSE, length(x)),
  addl = rep(0, length(x)),
  ii = rep(0, length(x)),
  index = rep(1, length(x)),
  pre = TRUE,
  ...
)

Arguments

x

a numeric vector of event times

dose

length x logical indicating which of x are dose times

addl

length x integer: number of additional doses

ii

length x numeric: interdose interval for addl

index

length x factor (optional) indicating subgroups to evaluate

pre

assume that simultaneous sample precedes implied dose

...

passed to tod()

Value

numeric

See Also

tod

Other tad: tod()

Examples

data(tad1)
x <- tad1
head(x)
x$tad <- tad(
   x = x$TIME,
   dose = x$EVID %in% c(1,4) & is.na(x$C),
   addl = x$ADDL,
   ii = x$II,
   index = x$ID
 )
head(x)

A NONMEM-like Dataset

Description

A dataset showing dose and and observation records for several subjects. Doses are duplicated across compartments 1 and 2 as for mixed absorption modeling.

Usage

data(tad1)

Details

  • C. An exclusion flag, NA by default, or 'C'.

  • ID. Integer subject identifier.

  • TIME. Numeric event time (h).

  • EVID. Event type identifier: observation (0) or dose (1).

  • CMT. Event compartment: dose (1), central (2) or peripheral (4).

  • AMT. Amount of dose (mg).

  • RATE. NONMEM RATE item.

  • ADDL. Number of additional doses, or NA for observations.

  • II. Interdose interval for additional doses, or NA for observations.

  • DV. Observation placeholder.


Calculate Time of Most Recent Dose

Description

Calculates time of most recent dose.

Usage

tod(x, ref, addl, ii, pre = T, ...)

Arguments

x

a numeric vector of event times

ref

length x vector of reference dose times

addl

length x integer: number of additional doses

ii

length x numeric: interdose interval for addl

pre

assume that simultaneous sample precedes implied dose

...

ignored

Value

numeric

See Also

tad

Other tad: tad()


Tweak a Model by Default

Description

Tweaks a model by jittering initial estimates. Creates a new model directory in project context and places the model there. Copies helper files as well. Expects that x is a number. Assumes nested directory structure (run-specific directories).

Usage

## Default S3 method:
tweak(
  x,
  project = getOption("project", getwd()),
  ext = getOption("modex", "ctl"),
  start = NULL,
  n = 10,
  include = ".def$",
  ...
)

Arguments

x

object

project

project directory (can be expression)

ext

file extension for control streams

start

a number to use as the first modelname

n

the number of variants to generate (named start:n)

include

regular expressions for files to copy to new directory

...

pass ext to over-ride default model file extension

Value

character: vector of names for models created

See Also

Other tweak: tweak(), tweak.init(), tweak.inits(), tweak.model()


Tweak Model

Description

Tweaks model.

Usage

## S3 method for class 'model'
tweak(x, sd = 0.13, digits = 3, ...)

Arguments

x

model

sd

numeric

digits

integer

...

passed arguments

Value

model

See Also

Other tweak: tweak(), tweak.default(), tweak.init(), tweak.inits()

Examples

# Create a working project.
source <- system.file(package = 'nonmemica','project')
target <- tempdir()
target <- gsub('\\\\','/',target) # for windows
source
target
file.copy(source,target,recursive = TRUE)
project <- file.path(target,'project','model')

# Point project option at working project
options(project = project)
library(magrittr)

# Make ten new models with slightly different initial estimates.
1001 %>% tweak

Create the Updated Version of Character

Description

Creates the updated version of character by treating as a modelname. Parses the associated control stream and ammends the initial estimates to reflect model results (as per xml file).

Usage

## S3 method for class 'character'
updated(x, initial = estimates(x, ...), parse = TRUE, verbose = FALSE, ...)

Arguments

x

character

initial

values to use for initial estimates (numeric)

parse

whether to parse the initial estimates, etc.

verbose

extended messaging

...

passed arguements

Value

model

See Also

Other updated: updated(), updated.numeric()


Get Upper Bounds for Model Initial Estimates

Description

Gets upper bounds for model initial estimates.

Usage

## S3 method for class 'model'
upper(x, ...)

Arguments

x

model

...

dots

See Also

Other upper: upper(), upper<-(), upper<-.model()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% as.model %>% upper

Set Upper Bounds for Model Initial Estimates

Description

Sets upper bounds for model initial estimates.

Usage

## S3 replacement method for class 'model'
upper(x) <- value

Arguments

x

model

value

numeric

See Also

Other upper: upper(), upper.model(), upper<-()


Evaluate Xpath Expression

Description

Evaluates an xpath expression.

Usage

xpath(x, ...)

Arguments

x

xml_document

...

passed arguments

Details

The resulting nodeset is scavenged for text, and coerced to best of numeric or character.

See Also

Other xpath: as.xml_document(), as.xml_document.character(), as.xml_document.numeric(), xpath.default(), xpath.xml_document()

Examples

library(magrittr)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% xpath('//etashrink/row/col')

Evaluate xpath Expression in Default Context

Description

Coerces x to xml_document and evaluates.

Usage

## Default S3 method:
xpath(x, ...)

Arguments

x

default

...

passed arguments

Value

vector

See Also

Other xpath: as.xml_document(), as.xml_document.character(), as.xml_document.numeric(), xpath(), xpath.xml_document()


Evaluate xpath Expression in Document Context

Description

Evaluates an xpath expression for a given document.

Usage

## S3 method for class 'xml_document'
xpath(x, xpath, ...)

Arguments

x

xml_document

xpath

xpath expression to evaluate

...

ignored

Details

The resulting nodeset is scavenged for text, and coerced to best of numeric or character.

Value

vector

See Also

Other xpath: as.xml_document(), as.xml_document.character(), as.xml_document.numeric(), xpath(), xpath.default()