Interpret LMTP positivity via effective sample sizes

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,
  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).

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
} # }