risk / wire operation
Value-at-Risk & Conditional VaR
totalfinance.risk.value_at_risk
Estimate Value-at-Risk (VaR) and Conditional VaR / expected shortfall from a return series. Methods: historical (empirical quantile, default), parametric (Gaussian, optional Cornish-Fisher for skew/kurtosis), or monteCarlo. Both are positive loss magnitudes at the given `confidence`; the horizon scales by √-time. The applied confidence/method/horizon ride `assumptions` (with the resolved seed/samples for monteCarlo) and warnings ride `diagnostics`.
| Pack / profiles | risk / default, full, portfolio |
|---|---|
| Default discovery | Included |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | small / Do not assume inline interruption |
| Handle-eligible inputs | None |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "number"
},
"description": "Periodic returns as decimals (e.g. 0.01 = +1%)"
},
"confidence": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Confidence level in (0, 1); default 0.95"
},
"method": {
"type": "string",
"enum": [
"historical",
"parametric",
"monteCarlo"
],
"description": "Estimation method; default historical"
},
"horizonPeriods": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Holding-period horizon in periods; scales by √-time; default 1"
},
"cornishFisher": {
"type": "boolean",
"description": "Parametric only: Cornish-Fisher adjustment for skew/excess-kurtosis"
},
"samples": {
"type": "integer",
"maximum": 1000000,
"exclusiveMinimum": 0,
"description": "Monte-Carlo only: number of simulated paths; default 10000, capped at 1,000,000 (compute is bounded BEFORE the work starts, not just by the deadline)."
},
"seed": {
"type": "integer",
"description": "Monte-Carlo only: PRNG seed; default 0"
}
},
"additionalProperties": false,
"required": [
"returns"
]
}Output schema
{
"type": "object",
"properties": {
"value": {
"type": "object",
"properties": {
"valueAtRisk": {
"type": "number",
"description": "Positive loss magnitude at `confidence`"
},
"conditionalValueAtRisk": {
"type": "number",
"description": "Conditional VaR / expected shortfall (≥ valueAtRisk)"
}
},
"required": [
"valueAtRisk",
"conditionalValueAtRisk"
]
},
"assumptions": {
"type": "object",
"description": "confidence, method, horizonPeriods, cornishFisher, conventionsVersion (+ seed/samples when method is monteCarlo)"
},
"diagnostics": {
"type": "object",
"description": "method + warnings"
}
},
"required": [
"value",
"assumptions",
"diagnostics"
]
}