cap_exposure: Apply post-weight exposure caps

Description

Row-wise caps on a wide weights table (Date + symbols):

per-symbol cap (max_per_symbol)
optional per-group cap (max_per_group) using group_map

Usage

cap_exposure(
  weights,
  max_per_symbol = NULL,
  group_map = NULL,
  max_per_group = NULL,
  allow_short = FALSE,
  renormalize = c("none", "down", "both"),
  renormalize_down = FALSE,
  renorm = NULL,
  cash_col = NULL,
  caps = NULL
)
cap_exposure(
  weights,
  max_per_symbol = NULL,
  group_map = NULL,
  max_per_group = NULL,
  allow_short = FALSE,
  renormalize = c("none", "down", "both"),
  renormalize_down = FALSE,
  renorm = NULL,
  cash_col = NULL,
  caps = NULL
)

Value

data.table of capped (and optionally renormalized) weights.

Arguments

weights: data.frame/data.table: columns Date, then symbols.
max_per_symbol: numeric scalar or named vector (absolute cap per symbol).
group_map: optional named character vector or data.frame(symbol,group).
max_per_group: optional numeric scalar (per-group gross cap).
allow_short: logical; if FALSE clamp negatives to 0.
renormalize: character: one of "none", "down", "both". Default "none".
renormalize_down: logical; deprecated alias for down-only (kept for compatibility).
renorm: logical; deprecated alias; if TRUE acts like renormalize="both".
cash_col: optional character; if provided, set to 1 - sum(pmax(w,0)).
caps: optional list; alternative to split args (see details above).

Details

Negatives are clamped to 0 unless allow_short = TRUE.

Renormalization options:

renormalize = "none": leave gross (sum of positive weights) as is.
renormalize = "down": if gross > 1, scale down so gross == 1.
renormalize = "both": if 0 < gross != 1, scale so gross == 1.

The argument renorm (logical) is a deprecated alias; TRUE behaves like renormalize = "both".

The caps list form is supported:

max_per_symbol: Maximum absolute weight per symbol (0-1).
max_per_group: Maximum gross weight per group (0-1).
group_map: Named character vector mapping symbol -> group.