Model Object Lifecycle

DSAMbayes model objects (blm, hierarchical, pooled) are mutable S3 lists that progress through a well-defined sequence of states. Understanding these states helps avoid calling post-fit accessors on an unfitted object or forgetting to compile before fitting.

State-machine diagram

                        ┌─────────────────────────────────────────┐
                        │           CREATED                       │
                        │  blm(), blm.formula(), blm.lm(),        │
                        │  as_bayes_lm_updater()                  │
                        │  Fields set: .formula, .original_data,  │
                        │    .prior, .boundaries                  │
                        └──────────────┬──────────────────────────┘
                                       │
            ┌──────────────────────────┼──────────────────────────┐
            ▼                          ▼                          ▼
    set_prior(obj, …)         set_boundary(obj, …)        set_date(obj, …)
    Mutates .prior            Mutates .boundaries         Sets .date_var
            │                          │                          │
            └──────────────────────────┼──────────────────────────┘
                                       │
                    (optional: pool() transitions blm → pooled,
                     resets .prior/.boundaries, adds .pooling_vars/.pooling_map)
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           CONFIGURED                    │
                        │  Priors, boundaries, date variable are  │
                        │  set (may still use defaults).          │
                        └──────────────┬──────────────────────────┘
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           COMPILED                      │
                        │  compile_model(obj)                     │
                        │  Sets .stan_model                       │
                        │  (pre_flight_checks auto-compiles if    │
                        │   .stan_model is NULL)                  │
                        └──────────────┬──────────────────────────┘
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           PRE-FLIGHTED                  │
                        │  pre_flight_checks(obj, data)           │
                        │  Validates formula/data compatibility,  │
                        │  auto-compiles and auto-sets date_var   │
                        │  if missing. Sets .response_transform,  │
                        │  .response_scale.                       │
                        └──────────────┬──────────────────────────┘
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           FITTED                        │
                        │  fit(obj) / fit_map(obj)                │
                        │  Calls pre_flight_checks internally,    │
                        │  then prep_data_for_fit → rstan.        │
                        │  Sets .stan_data, .date_val, .posterior │
                        └──────────────┬──────────────────────────┘
                                       │
                   ┌───────────────────┼───────────────────┐
                   ▼                   ▼                   ▼
           get_posterior(obj)    fitted(obj)         decomp(obj)
           Returns tibble of    Predicted values    Decomposition
           posterior draws      (yhat)              via DSAMdecomp
                   │                                       │
                   ▼                                       ▼
           optimise_budget(obj, …)                         Further analysis
           Budget allocation
           (requires fitted model)

States and key fields

State	Entry point	Fields populated
Created	`blm()`, `blm.formula()`, `blm.lm()`, `as_bayes_lm_updater()`	`.formula`, `.original_data`, `.prior`, `.boundaries`, `.response_transform`, `.response_scale`
Configured	`set_prior()`, `set_boundary()`, `set_date()`	Mutates `.prior`, `.boundaries`, `.date_var`
Pooled	`pool(obj, grouping_vars, map)`	Adds `.pooling_vars`, `.pooling_map`; resets `.prior`, `.boundaries`; class becomes `pooled`
Compiled	`compile_model(obj)`	`.stan_model`
Pre-flighted	`pre_flight_checks(obj, data)`	`.response_transform`, `.response_scale`; auto-sets `.stan_model`, `.date_var` if missing
Fitted	`fit(obj)` / `fit_map(obj)`	`.stan_data`, `.date_val`, `.posterior`

Post-fit accessors

These functions require a fitted model (.posterior is not NULL):

Accessor	Returns	Notes
`get_posterior(obj)`	Tibble of posterior draws (coefficients, metrics, yhat)	Back-transforms to original scale when `scale=TRUE`
`fitted(obj)`	Predicted values (yhat) on original scale
`get_optimisation(obj)`	Optimisation results tibble	Only for MAP-fitted models (`.posterior` inherits `optimisation`)
`decomp(obj)`	Predictor-level decomposition via DSAMdecomp
`optimise_budget(obj, …)`	Budget allocation results	Requires fitted model with media terms
`chain_diagnostics(obj)`	MCMC chain diagnostic summary	Only for MCMC-fitted models

Guards and auto-transitions

pre_flight_checks() auto-compiles via compile_model() if .stan_model is NULL, and auto-sets .date_var to "date" if not already set.
fit() and fit_map() call pre_flight_checks() internally, so explicit compilation is optional.
get_posterior() aborts with a clear error if .posterior is NULL.
optimise_budget() aborts if the model has scale=TRUE and an offset is present (unsupported combination for the bayes_lm_updater class).

Object field reference

All fields are initialised by model_object_schema_defaults() in R/model_schema.R. The canonical field list:

Field	Type	Set by
`.original`	lm object or NULL	Constructor
`.formula`	formula	Constructor
`.original_data`	data.frame	Constructor
`.response_transform`	character(1)	Constructor / pre_flight_checks
`.response_scale`	character(1)	Constructor / pre_flight_checks
`.prior`	tibble	Constructor / set_prior
`.boundaries`	tibble	Constructor / set_boundary
`.stan_model`	stanmodel	compile_model
`.stan_data`	list	prep_data_for_fit (via fit)
`.posterior`	stanfit or optimisation	fit / fit_map
`.fitted`	logical(1)	Internal
`.offset`	matrix or NULL	prep_offset (via fit)
`.date_var`	character(1)	set_date / pre_flight_checks
`.date_val`	vector	fit / fit_map
`.cre`	list or NULL	apply_cre_data (hierarchical)
`.pooling_vars`	character	pool()
`.pooling_map`	data.frame	pool()
`.positive_prior_parameterization`	character(1)	Runner config

Runner-injected fields

These are set by the YAML/CLI runner (run_from_yaml()) for artifact writing and are not part of the core modelling API:

.runner_config, .runner_kpi_type, .runner_identifiability
.runner_time_components, .runner_budget_optimisation
.runner_model_selection, .runner_model_type