Parse and expand an MFL search space

Description

Parses a Model Feature Language (MFL) search space - Pharmpy’s grammar, so a space is portable between the two - and, when a base model is supplied, resolves every @-symbol and wildcard against it. That is what makes an interactive space debuggable: COVARIATE?(@IIV, @CONTINUOUS, [pow, lin])becomes the explicit parameter x covariate x effect set it stands for on your model, before committing to a run.

Usage

ferx_search_space(mfl, model = NULL, data = NULL)

# S3 method for ferx_search_space
print(x, ...)

Arguments

  • mfl: MFL source text, a ferx_search_config (its [space] is used, together with its base / data when model is not given), or a ferx_search_space to re-resolve.
  • model: Optional path to a .ferx model, or a ferx_model object. NULL parses the space without resolving it.
  • data: Optional path to the dataset. Defaults to the model’s [data] block when the model declares one.
  • x: A ferx_search_space.
  • ...: Passed to print.data.frame.

Details

Symbols are resolved against the model’s [individual_parameters], its template line (pk NAME(...) / ode_template NAME(...)), its [covariates] block and the dataset: @IIV is every individual parameter carrying an eta, @PK every parameter bound on the template line, @CONTINUOUS / @CATEGORICAL the covariates declared with that type. LET(NAME, [...]) overrides a built-in of the same name. A symbol that resolves to nothing drops its feature with a note (Pharmpy’s behaviour) rather than erroring; a name that is neither an individual parameter nor a declared covariate is an error naming it. Resolution needs the dataset (the covariate columns come from it), so data - or a [data] block in the model - is required whenever model is given.

Seealso

[ferx_search_coverage](ferx_search_coverage.qmd), [ferx_search_config](ferx_search_config.qmd)Other search: [ferx_allometry](ferx_allometry.qmd), [ferx_amd](ferx_amd.qmd), [ferx_amd_plan](ferx_amd_plan.qmd), [ferx_covsearch](ferx_covsearch.qmd), [ferx_globalsearch](ferx_globalsearch.qmd), [ferx_iivsearch](ferx_iivsearch.qmd), [ferx_iovsearch](ferx_iovsearch.qmd), [ferx_modelsearch](ferx_modelsearch.qmd), [ferx_ruvsearch](ferx_ruvsearch.qmd), [ferx_search_config](ferx_search_config.qmd), [ferx_search_coverage](ferx_search_coverage.qmd), [ferx_search_results](ferx_search_results.qmd)

Concept

search

Value

A data frame of class ferx_search_space with one row per feature - feature (the rendered statement), keyword and optional (TRUE for an exploratory FEATURE?) - holding the resolved (ground) features when a model was supplied and the space as written otherwise. Attributes: mfl (the source text), resolved (logical), parsed (the unresolved feature table), covariate_effects (a data frame of the ground covariate effects: parameter, covariate, effect, op, optional) and notes (features the resolver dropped, and anything else it wants seen once).

Examples

# Parse only - no model needed
ferx_search_space("COVARIATE?(@IIV, @CONTINUOUS, [pow, lin])")

# Expanded against a model: what the search would actually explore
ex <- ferx_example("two_cpt_oral_cov")
sp <- ferx_search_space(
  "COVARIATE?(@IIV, @CONTINUOUS, [pow, lin])",
  model = ex$model, data = ex$data
)
attr(sp, "covariate_effects")