Contrast estimates from a fitted design

Description

The second step of the two-step API (mirroring causatr::contrast() and the etverse convention): given a matcha() fit, compute the requested effect on the chosen scale and return a matchatr_result. matcha() resolves the sampling design and runs the analysis; contrast() turns the fitted estimates into a reported effect with uncertainty.

Usage

contrast(
  fit,
  type = c("difference", "ratio", "or", "hr"),
  ci_method = c("model", "sandwich", "bootstrap"),
  conf_level = 0.95,
  ...
)

Arguments

fit	A matchatr_fit object returned by matcha().
type	Character contrast scale: “difference”, “ratio”, “or” (odds ratio), or “hr” (hazard ratio, for the nested case-control risk-set design). When omitted, it defaults to the estimand the design identifies — “or” for the classical odds-ratio engines (unmatched / matched case-control), “hr” for the nested case-control design, “difference” otherwise. Each conditional design identifies exactly one scale, so the off-design request (an odds ratio from a risk-set design, or vice versa) aborts with matchatr_unidentified_estimand.
ci_method	Character variance source for the interval: “model” (information-matrix Wald, the default), “sandwich” (Huber-White robust), or “bootstrap”.
conf_level	Numeric confidence level for the interval, a single number strictly in (0, 1). Defaults to 0.95.
…	Reserved for estimator-specific contrast arguments.

Details

What is identifiable depends on the design. From an unmatched case-control sample only the conditional odds ratio (type = “or”) is identified: under separate case / control sampling the marginal outcome frequency is fixed, so a marginal risk difference (type = “difference”) or risk ratio (type = “ratio”) requires the source-population prevalence q0 and a case-control-weighted estimator. Requesting an unidentified estimand aborts with the classed matchatr_unidentified_estimand condition.

A fit whose engine has no wired estimator carries no estimates — its model slot is NULL — so contrast() validates its arguments and then aborts with matchatr_not_estimated.

For an odds-ratio result the confidence interval is Wald on the log scale and exponentiated, so it is asymmetric on the OR scale: estimate +/- z * se does not reproduce the reported ci_lower / ci_upper (the se is the delta-method OR-scale SE, kept for reference). Use the reported bounds.

Value

A matchatr_result object carrying the estimates, the contrasts, and their variance-covariance matrix.

See Also

matcha(), tidy.matchatr_fit()

Examples

library("matchatr")

set.seed(1)
df <- data.frame(
  case = rep(c(1, 0), each = 100),
  x = rbinom(200, 1, 0.4),
  age = rnorm(200, 50, 10)
)
fit <- matcha(df, outcome = "case", exposure = "x",
              design = unmatched_cc(), confounders = ~ age)
# The conditional odds ratio is identified:
contrast(fit, type = "or")

<matchatr_result>
 Estimator:  logistic  (engine: glm_logistic)
 Estimand:   conditional OR
 Contrast:   Odds ratio
 CI method:  model
 N:          200

Contrasts:
   comparison estimate        se  ci_lower ci_upper
       <char>    <num>     <num>     <num>    <num>
1:          x 1.127078 0.3239669 0.6416305 1.979808

# The risk difference is not (no prevalence q0):
try(contrast(fit, type = "difference"))

Error in contrast(fit = fit, type = "difference") : 
  The risk difference is not identified from an unmatched case-control sample without the source-population prevalence q0.
ℹ Report the conditional odds ratio with `type = "or"`.
ℹ For a marginal risk difference / ratio, supply `prevalence =` on the design and use a case-control-weighted estimator (e.g. `estimator = "ccw_gformula"`).