| name | drmtmb-adapter |
| description | How drmSEM talks to drmTMB — ONLY through R/extractors.R. The drmTMB return-shape facts, the dpar:term coefficient convention, and the rule to confirm parameterizations against a live fit before trusting samplers. |
drmTMB adapter (R/extractors.R only)
EVERY assumption about a fitted drmTMB object's internal shape lives in
R/extractors.R. No other file may reach into a drmTMB object directly. If
drmTMB's internals shift, only this file changes.
Rule
- New code that needs something from a fit calls an
extractors.R helper. If
the helper doesn't exist, ADD it there — do not poke fit$... from
effects.R, dsep.R, paths.R, etc.
- Guard every drmTMB call with
drm_require_drmTMB() (aborts with an install
hint when drmTMB is absent).
Verified drmTMB facts (against 0.1.3.9000, github itchyshin/drmTMB)
bf() / drmTMB::drm_formula() → object with $calls, $names, $entries.
Each entry has $dpar, $response, $lhs, $rhs.- A fitted object carries
$formula (the bf object), $family, $data,
$coefficients (named list keyed by dpar → named numeric vector).
coef(obj, dpar), fixef(obj, dpar), vcov(obj) with dimnames "dpar:term"
— vcov needs the model fitted with control = drm_control(se = TRUE).logLik(obj) (with df attr), is_converged(obj),
predict_parameters(obj, newdata, dpar, type = c("response","link")).
The dpar:term coefficient convention (load-bearing)
$coefficients[[dpar]] is a named numeric vector; names are bare terms
("(Intercept)", "temp", "habitatB").vcov rows/cols are paste0(dpar, ":", term). To look up an SE for a path,
build the key "dpar:term" and index V[key, key] (see paths.drm_sem).drm_fit_coef_vector() flattens to "dpar:term" names; drm_draw_beta()
rebuilds per-dpar keys to slice the MVN covariance block.
Helper map (don't duplicate these)
- Identity/metadata:
is_drmTMB_fit, drm_fit_formula, drm_fit_entries,
drm_fit_family/drm_family_name, drm_fit_data, drm_fit_response,
drm_fit_components, drm_fit_component_predictors.
- Estimates:
drm_fit_coef, drm_fit_coef_vector, drm_fit_vcov
(NULL when SEs unavailable / Hessian not PD), drm_fit_logLik,
drm_fit_converged.
- Prediction & refit:
drm_predict_parameters (wraps predict_parameters),
drm_refit_augmented (d-sep: appends + X to every targeted component RHS,
refits with se = TRUE), drm_fixed_design.
model.matrix coding assumption
drm_fixed_design() rebuilds the fixed-effect formula per component (bars and
structured markers dropped via drm_drop_bars/drm_strip_markers), runs
stats::model.matrix(), and aligns/zero-fills columns to the fitted coefficient
names. This ASSUMES drmTMB codes fixed effects with standard model.matrix()
contrasts. That assumption is isolated here — keep it here.
Before trusting a sampler or propagation parameterization
The realized-value samplers in simulate_effects.R assume specific
response-scale parameterizations (e.g. nbinom2 size = 1/sigma,
beta shapes from mu*phi). CONFIRM these against a live drmTMB fit
(predict_parameters + a known DGP recovery test) before trusting any new
sampler or family. Add a recovery test; do not infer the parameterization from
memory.
