psw: Propensity Score Weight Vectors

In propensity: A Toolkit for Calculating and Working with Propensity Scores

Propensity Score Weight Vectors

Description

psw objects are numeric vectors that carry metadata about propensity score weights, including the target estimand and whether the underlying propensity scores were trimmed, truncated, or calibrated.

Most users will encounter psw objects as return values from wt_ate() and related weight functions. These constructor and helper functions are useful for inspecting weight objects or for package developers extending propensity.

Usage

new_psw(
  x = double(),
  estimand = NULL,
  stabilized = FALSE,
  trimmed = FALSE,
  truncated = FALSE,
  calibrated = FALSE,
  ...
)

psw(
  x = double(),
  estimand = NULL,
  stabilized = FALSE,
  trimmed = FALSE,
  truncated = FALSE,
  calibrated = FALSE
)

is_psw(x)

is_stabilized(wt)

is_causal_wt(x)

as_psw(x, estimand = NULL)

estimand(wt)

estimand(wt) <- value

Arguments

x	For psw() and new_psw(): a numeric vector of weights (default: double()). For is_psw(), is_causal_wt(), and as_psw(): an object to test or coerce.
estimand	A character string identifying the target estimand (e.g., "ate", "att", "ato"). Defaults to NULL.
stabilized	Logical. Were the weights stabilized? Defaults to FALSE.
trimmed	Logical. Were the weights derived from trimmed propensity scores? Defaults to FALSE.
truncated	Logical. Were the weights derived from truncated propensity scores? Defaults to FALSE.
calibrated	Logical. Were the weights derived from calibrated propensity scores? Defaults to FALSE.
...	Additional attributes stored on the object (developer use only).
wt	A psw or causal_wts object.
value	A character string: the new estimand to assign.

Details

Constructors

• psw() is the user-facing constructor. It coerces x to double and validates inputs before creating the object.

• new_psw() is the low-level constructor intended for developers. It assumes x is already a double vector and performs minimal validation.

• as_psw() coerces an existing numeric vector to a psw object.

Queries

• is_psw() tests whether an object is a psw vector.

• is_causal_wt() tests whether an object inherits from the broader causal_wts class (which includes psw objects).

• estimand() and ⁠estimand<-⁠ get and set the estimand attribute.

• is_stabilized() returns TRUE if the weights are stabilized.

Arithmetic and combining

Arithmetic operations on psw objects preserve the class and attributes, so operations like normalization (weights / sum(weights)) retain metadata. Combining psw objects with c() preserves the class only when all metadata matches; mismatched metadata produces a warning and falls back to a plain numeric vector.

Subsetting with [ preserves class and attributes. Summary functions (sum(), mean(), etc.) return plain numeric values.

Value

• new_psw(), psw(), as_psw(): A psw vector.

• is_psw(), is_causal_wt(), is_stabilized(): A single logical value.

• estimand(): A character string, or NULL if no estimand is set.

• ⁠estimand<-⁠: The modified psw object (called for its side effect).

See Also

wt_ate(), wt_att(), wt_atu(), wt_atm(), wt_ato() for calculating propensity score weights (which return psw objects).

ps_trim(), ps_trunc(), and ps_calibrate() for modifying propensity scores before weight calculation.

Examples

# Create psw objects directly
w <- psw(c(1.2, 0.8, 1.5), estimand = "ate")
w

# Query metadata
is_psw(w)
estimand(w)
is_stabilized(w)

# Coerce a plain numeric vector
as_psw(c(1.0, 2.0), estimand = "att")

# Arithmetic preserves the psw class
w / sum(w)

# Combining: compatible metadata is preserved
x <- psw(c(1.2, 0.8), estimand = "ate")
y <- psw(c(1.1, 0.9), estimand = "ate")
c(x, y)

# Combining: incompatible metadata warns and returns numeric
x <- psw(c(1.2, 0.8), estimand = "ate")
y <- psw(c(1.1, 0.9), estimand = "att")
c(x, y)

propensity documentation built on March 3, 2026, 1:06 a.m.