Skip to contents

Create a Custom Space (PML Model) from Code

create_CustomSpace.Rd

Parses a character string containing custom PML code to create a structured representation within the PMLModels framework. This allows integrating user-defined models with the package's modification and generation tools.

Usage

create_CustomSpace(CustomCode = character(), SpaceName = character())

Arguments

CustomCode

A character string containing the complete custom PML code (e.g., the content of a test(){...} block, potentially excluding the test(){ and closing } depending on usage context, although including them is safer for parsing). Multi-line strings are collapsed. Cannot be empty.

SpaceName

An optional character string specifying the name for this custom model space. This name will be used as the key for this model within the returned PMLModels list. If omitted or an empty string (""), a unique identifier will be created by concatenating the letter "l" with the number of characters in CustomCode. Providing a meaningful name is recommended for clarity, especially when working with multiple custom models. Ensure provided names are unique if creating multiple custom spaces intended to coexist.

Value

A list object of class PMLModels. This list contains a single element, named according to the provided or generated SpaceName. The value of this element is an internal list structure (created by the internal CustomSpace function) holding the original code and parsed components.

Details

This function acts as a parser for custom PML code. It attempts to identify and extract various PML statements within the provided CustomCode string. Recognized statements include:

  • Observations/Responses: observe(), error(), multi(), ordinal(), count(), event(), LL()

  • Structural Parameters: stparm()

  • Covariates: covariate() (parsed as backward), fcovariate() (parsed as forward), interpolate()

  • Dosing: dosepoint(), dosepoint2()

  • Parameter Definitions: ranef(), fixef()

  • Model Dynamics: deriv(), cfMicro(), cfMacro(), cfMacro1(), transit(), delayInfCpt()

  • Other Compartments: urinecpt()

The function cleans the code (removes comments, standardizes spacing) for parsing most statements but uses the original code for stparm and fixef parsing to preserve complex structures.

The extracted components are stored as specific S3 objects (e.g., ObservationCustom, StParmCustom, CovariateCustom, DosepointCustom) within the list element corresponding to the SpaceName. This structured representation allows the custom model to be potentially inspected or manipulated by other package functions, although interacting with built-in models via functions like modify_StParm is generally more robust than modifying custom code components directly.

Examples

# Example custom PML code (simplified)
custom_pml <- "test() {
  cfMicro(A1, Cl / V)
  dosepoint(A1)
  C = A1 / V
  error(CEps = 1)
  observe(CObs = C + CEps)
  stparm(V = tvV * exp(nV))
  stparm(Cl = tvCl * exp(nCl))
  fixef(tvV = c(, 1, ))
  fixef(tvCl = c(, 1, ))
  ranef(diag(nV, nCl) = c(1, 1))
}
"

# Create a custom space with an explicit name
custom_model_set <-
  create_CustomSpace(CustomCode = custom_pml,
                      SpaceName = "My1CptOral")

# Print the structure (will show parsed components within the list element)
# print(custom_model_set)

# List the name of the created space
names(custom_model_set) # Output: "My1CptOral"
#> [1] "My1CptOral"

# Create a custom space with an automatically generated name
custom_model_set_auto_name <- create_CustomSpace(CustomCode = custom_pml)
names(custom_model_set_auto_name)
#> [1] "l248"