Calculate Population-Level Demand Metrics for TMB Model

Usage

# S3 method for class 'beezdemand_tmb'
calc_group_metrics(object, at = NULL, ...)

Arguments

object: A beezdemand_tmb object.
at: Named list of factor-level filters or continuous-covariate value overrides (e.g. list(condition = "C1", FTND_z = 0.5)). When NULL (default), continuous covariates are evaluated at their training mean and factors are marginalized across observed levels (equal weights). When supplied, conditions the parameter EMMs to the specified factor levels and/or covariate values before deriving Pmax/Omax. Same shape as the at argument of get_demand_param_emms.beezdemand_tmb and get_demand_comparisons.beezdemand_tmb.
...: Additional arguments (currently unused).

Value

A list with Pmax, Omax, Qmax, elasticity_at_pmax, method, and conditioned_on describing the reference point used. The conditioned_on field reports the actual conditioning applied (covariate values used, factor treatment per factor) so programmatic consumers do not have to re-derive it.

Marginalization order

For derived metrics (Pmax/Omax/Qmax) that depend nonlinearly on Q0 and alpha jointly, this function marginalizes parameters first then derives metrics:

Compute log-Q0 and log-alpha EMMs at each cell of the reference grid produced by .tmb_build_emm_ref_grid().
Marginalize each parameter across factor cells with equal weights (matches the emmeans default).
Derive Pmax/Omax/Qmax from the marginalized log-parameters at the user-supplied (or training-mean default) covariate point.

The result is "metrics evaluated at the average parameter values" rather than "average metrics across cells". The two answers differ for nonlinear transforms. The convention matches the parameter-level marginalization used by get_demand_param_emms().

Marginalisation policy (TMB vs NLME)

This method averages the log-scale linear predictors with equal weight over the factor cells observed in the fitting data and then exponentiates. The NLME method (calc_group_metrics.beezdemand_nlme()) follows the same policy: per-cell EMMs from emmeans, rows for unobserved cells dropped, equal-weight geometric mean over the remaining cells. Cells of the full factorial crossing with no subjects are never averaged over by either backend. The two agree for any design fit in log space and can differ only when the NLME fit uses param_space = "natural". In both backends continuous covariates are held at the training mean unless at supplies a single value; a multi-value continuous at entry warns and uses its first value.

Examples

# \donttest{
data(apt)
fit <- fit_demand_tmb(apt, equation = "exponential", verbose = 0)
#>   equation='exponential': Dropped 14 zero-consumption observations (146 remaining).
calc_group_metrics(fit)
#> $Pmax
#> [1] 11.6482
#> 
#> $Omax
#> [1] 23.92321
#> 
#> $Qmax
#> [1] 2.053813
#> 
#> $elasticity_at_pmax
#> [1] -1
#> 
#> $method
#> [1] "analytic_lambert_w"
#> 
#> $pmax_at_bound
#> [1] FALSE
#> 
#> $conditioned_on
#> NULL
#> 
# Conditioned at a specific covariate value:
# calc_group_metrics(fit_with_cov, at = list(FTND_z = 1))
# }