fs_dgm_scale: Sampling Scale of the Difference-in-Means Estimator

View source: R/fs_dgm_scale.R

fs_dgm_scaleR Documentation

Sampling Scale of the Difference-in-Means Estimator

Description

Computes the finite-population sampling scale of the within-region difference-in-means estimator directly from a data generating mechanism's individual-level potential outcomes.

Usage

fs_dgm_scale(
  dgm,
  regions = NULL,
  harm_col = "flag_harm",
  rand_ratio = 1,
  labels = c("Q", "Qc", "S")
)

Arguments

dgm

An object of class "glm_dgm" from generate_glm_dgm.

regions

Optional named list of region specifications. Each element is either a logical vector of length nrow(dgm$df_super) or an integer vector of row indices. Defaults to NULL, which uses the true harm region, its complement, and the whole super-population.

harm_col

Character. Name of the true-region indicator column in df_super. Default "flag_harm".

rand_ratio

Numeric. Treatment:control randomisation ratio, so the randomisation probability is rand_ratio / (1 + rand_ratio). Default 1 (1:1), matching simulate_from_glm_dgm.

labels

Optional character vector of length 3 renaming the default regions. Ignored when regions is supplied. Default c("Q", "Qc", "S").

Details

For a region g the estimator is the within-region difference in arm means. Conditioning on the realized arm counts,

\mathrm{Var}[\hat\beta(g)] = V_{\mathrm{eff}}(g) / (n P(g)),

with the region- and n-free constant

V_{\mathrm{eff}}(g) = V_1(g)/p + V_0(g)/(1-p),

where p is the randomisation probability and V_w(g) is the total within-arm outcome variance in g under arm w:

V_w(g) = m_g[v_w] + V_g[\mu_w].

Here \mu_w is the arm mean surface, v_w(x) = \mathrm{Var}(Y \mid X = x, W = w) the conditional outcome variance, and m_g[\cdot], V_g[\cdot] finite-population moments over the rows of the super-population lying in g. The conditional variance is supplied by the outcome family:

continuous

v_w = \sigma^2, the residual variance (constant).

binary

v_w = p_w (1 - p_w).

count

v_w = \mu_w (Poisson).

Value

An object of class c("fs_dgm_scale", "list"):

regions

Data frame, one row per region, with columns region, n_g, P_g, m_mu0, m_mu1, m_tau, V_mu0, V_mu1, V_tau, C_mu0_tau, v_cond0, v_cond1, V_arm0, V_arm1, bracket, V_eff.

sigma

Residual standard deviation for continuous outcomes, otherwise NA_real_.

outcome_type, effect_measure

Copied from dgm.

rand_ratio, p_treat

Allocation used.

n_super

Super-population size.

Balanced-arm reading

At 1:1 allocation V_{\mathrm{eff}}(g) = 2\{V_0(g) + V_1(g)\}, and bracket = V_{\mathrm{eff}}(g)/4 admits the decomposition

\sigma^2 + V_g[\mu_0] + C_g[\mu_0, \tau] + \tfrac12 V_g[\tau],

with \tau = \mu_1 - \mu_0 the conditional average treatment effect. The component columns are returned for every region and every outcome type; the decomposition above is exact for continuous outcomes at 1:1 allocation. Away from 1:1, bracket remains V_{\mathrm{eff}}/4 but no longer equals that sum, so prefer V_eff for any downstream calculation.

Idealisations

V_eff treats the region size and the arm split as fixed at their expectations. A trial draws n_g \sim \mathrm{Bin}(n, P(g)) and n_1 \mid n_g \sim \mathrm{Bin}(n_g, p), and by Jensen's inequality E[1/n_1 + 1/n_0] and E[1/n_g] exceed their fixed-count counterparts. Use fs_scale_se with jensen = TRUE for the unconditional standard deviation.

Scope

Exact for identity-scale effect measures ("MD", "RD", "IRD"), where the estimator is a difference in means. Ratio measures ("OR", "RR", "IRR") require a delta-method layer and are rejected rather than silently approximated.

See Also

fs_scale_se, generate_glm_dgm

Examples

## Not run: 
dgm <- generate_glm_dgm(..., outcome_type = "continuous",
                        effect_measure = "MD")
sc <- fs_dgm_scale(dgm)
sc$regions[, c("region", "P_g", "bracket", "V_eff")]

# Standard deviation of the estimator on the true region at n = 500
fs_scale_se(sc, n = 500, region = "Q")

# Arbitrary regions, e.g. a candidate family
fs_dgm_scale(dgm, regions = list(big = dgm$df_super$age > 40))

## End(Not run)


forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.