Retrieve model and fitmodel-style results for a selected covariate search scenario.

Dispatches on the type of x to resolve an archived covariate-search run folder and scenario, then loads the base model and run context from rsnlme_run.rds and reconstructs the scenario-specific model. Use listSCMRuns to enumerate scenarios in one or more such folders.

Usage

getSCMResults(x, scenario = NULL, enableIDs = NULL)

Arguments

x

One of:

A search-result data frame (from shotgunSearch() / stepwiseSearch()) with a searchRunDir attribute.
A single-row data frame from listSCMRuns().
An NlmePmlModel (resolves the latest archived run in its working directory).
A character path to an archived run folder (selects best scenario).
A character path to a scenario subfolder (uses that exact scenario).

scenario

Optional scenario identifier (label or token). Only allowed when x resolves to a run folder (not a specific scenario).

enableIDs

Optional comma-separated string or integer vector of enable IDs to select a scenario by its active PML enable() groups (matches the enableIDs column of scenario_index.csv). Only allowed when x resolves to a run folder.

Value

An scmResult object (list-like, with a custom print method) containing three elements:

model: The reconstructed NlmePmlModel for the scenario, with accepted parameter estimates.
fitmodelOutput: A list compatible with fitmodel() output. In addition to the file-derived elements, this list carries the self-describing fields: model (the reconstructed scenario model), params (resolved NlmeEngineExtraParams), runMode ("stepwise" or "shotgun"), runTime (wall-clock list), and RsNLMEVersion.
scenarioInfo: A single-row data frame with scenario metadata.

Details

When x is a row-subset of a search-result data frame and the caller does not specify a scenario explicitly, selection is restricted to the subset: if the archive's flagged best scenario is filtered out, the row with the lowest value of the search's selection criterion (-2LL, AIC, or BIC; recorded for stepwise searches and always -2LL for shotgun) within the subset is returned. For stepwise this need not match the engine's chosen winner, because the user has explicitly excluded that row by subsetting.

Archived run folders

Archived folders are created when shotgunSearch() or stepwiseSearch() is run with archiveResults = TRUE. During the engine run, NLME8 writes scenario outputs under a temporary SCM_<runId>/ directory in the model working directory (runId is a wall-clock timestamp, optionally suffixed with runLabel). After the engine finishes, collectJob() materialises the search result and the package renames that tree into a durable folder named stepwise_<runId> or shotgun_<runId> (on remote hosts the bundle SCM_<runId>.tar.gz is extracted first, then the bundle and any loose SCM_<runId>/ copy are removed). The final folder holds scenario_index.csv, per-scenario subfolders, Overall.csv, optional stepwise logs, and rsnlme_run.rds.