Interpret LMTP positivity via effective sample sizes
Source:R/margot_overlap_bullets.R
margot_interpret_lmtp_positivity.Rd
Builds a concise textual summary of LMTP density-ratio diagnostics for a single outcome. For each requested shift, the function computes effective sample sizes (ESS) by wave and for the pooled person-time using `colSums()` over the underlying density ratios. The output mirrors the filtering and labelling conventions used by [`margot_plot_lmtp_overlap_grid()`] for consistency between prose and graphics.
Usage
margot_interpret_lmtp_positivity(
x,
outcome,
shifts = NULL,
label_mapping = NULL,
waves = NULL,
remove_waves = NULL,
digits = 2,
include_methods = FALSE,
include_diagnostics = FALSE,
include_ipsi_context = TRUE,
treatment_label = NULL,
ipsi_example_g = NULL,
include_policy_rates = TRUE,
policy_rate_threshold = 0,
policy_rate_strict = TRUE,
include_deterministic_context = TRUE,
return = c("text", "list")
)
margot_interpret_lmtp_overlap(...)
Arguments
- x
LMTP run output (e.g., the result of [margot_lmtp()]) or any object that exposes `$density_ratios` in the same structure as the plot helpers.
- outcome
Character scalar giving the outcome name to summarise.
- shifts
Optional character vector of shifts to include (either full names such as `t5_pwi_z_shift_up` or cleaned suffixes such as `shift_up`). If `NULL`, all available shifts for the outcome are used.
- label_mapping
Optional named list passed to [transform_label()] for readable outcome/shift labels.
- waves
Optional integer vector of wave indices to keep (matching the column positions used by the overlap plot). Defaults to all available waves.
- remove_waves
Optional integer vector of waves to exclude after any inclusion via `waves`.
- digits
Integer number of decimal places to use when reporting ESS-based fractions (e.g., `ESS/N`).
- include_methods
Logical; if TRUE, prepends a methodological explanation of density ratios, their interpretation, and ESS computation (default: FALSE).
- include_diagnostics
Logical; if TRUE, appends detailed diagnostics per shift including zeros, range, quantiles, and tail probabilities (default: FALSE).
- include_ipsi_context
Logical; if TRUE and any `ipsi_*` shifts are included, prepends a short IPSI context block that explains the policy on the probability (risk) scale with a simple formula and small illustrative translations (default: TRUE).
- treatment_label
Character label used for $A_t$ in the IPSI context block. If NULL, attempts to infer a domain-appropriate label from model/shift names (e.g., "attendance" when shift/outcome names contain religious service keywords); otherwise falls back to "exposure". Default: NULL.
- ipsi_example_g
Numeric vector of example baseline risks g used to illustrate the transformation q = delta * g / ((1 - g) + delta * g) for the included delta values (default: `c(0.05, 0.10, 0.20)`).
- include_policy_rates
Logical; if TRUE and exposure-by-wave data are available and aligned with the density ratios, reports policy-implied exposure probabilities by wave using the reweighted mean p_hat_t = sum(r_i,t * A_i,t) / sum(r_i,t) on uncensored rows (default: TRUE). If required inputs are missing, silently skips this section.
- policy_rate_threshold
Numeric; when computing policy rates and the attached exposure columns are counts or continuous, converts them to a binary indicator 1(A_t op tau) before aggregation. Default tau = 0 (i.e., any exposure).
- policy_rate_strict
Logical; comparison operator used with the threshold when building the indicator: if TRUE uses '>' (strict), else uses '>=' (inclusive). Default TRUE.
- include_deterministic_context
Logical; if TRUE and any deterministic shifts are present (e.g., names starting with `shift_`), prepends a concise description of history‑dependent policies (e.g., A_t^d := d_t(A_t, H_t)) and, when possible, lists the named deterministic policies included (default: TRUE).
- return
Character; either `"text"` (default, a single markdown-ready string) or `"list"` (detailed components including the computed ESS tables).
Value
Either a single character string (default) or a list containing the header, per-shift lines, overview text, and the underlying ESS summaries when `return = "list"`.
Examples
if (FALSE) { # \dontrun{
# Basic usage
txt <- margot_interpret_lmtp_positivity(
fit,
outcome = "t5_pwi_z",
shifts = c("shift_up", "shift_down", "null"),
label_mapping = label_mapping
)
cat(txt)
# With methodological explanation
txt_methods <- margot_interpret_lmtp_positivity(
fit,
outcome = "t5_pwi_z",
shifts = c("shift_up", "shift_down", "null"),
label_mapping = label_mapping,
include_methods = TRUE
)
cat(txt_methods)
# With detailed diagnostics
txt_diagnostics <- margot_interpret_lmtp_positivity(
fit,
outcome = "t5_pwi_z",
shifts = c("shift_up", "shift_down", "null"),
label_mapping = label_mapping,
include_diagnostics = TRUE
)
cat(txt_diagnostics)
# Complete report with methods and diagnostics
txt_full <- margot_interpret_lmtp_positivity(
fit,
outcome = "t5_pwi_z",
shifts = c("shift_up", "shift_down", "null"),
label_mapping = label_mapping,
include_methods = TRUE,
include_diagnostics = TRUE
)
cat(txt_full)
# Get structured list output
result <- margot_interpret_lmtp_positivity(
fit,
outcome = "t5_pwi_z",
shifts = c("shift_up", "shift_down", "null"),
include_methods = TRUE,
include_diagnostics = TRUE,
return = "list"
)
# Access components: result$methods, result$diagnostics, result$shifts
} # }