Analytics¶
Sensitivity analysis, metrics, and advanced analytics functions.
Metrics¶
SimulationMetrics¶
SimulationMetrics
dataclass
¶
Computed metrics from a simulation run.
compute_metrics¶
compute_metrics(wealth_history, retirement_step)
¶
Compute simulation metrics from wealth history.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wealth_history
|
ndarray
|
(n_paths, n_steps+1) array of total wealth at each step. |
required |
retirement_step
|
int
|
Step index when retirement begins. |
required |
Returns:
| Type | Description |
|---|---|
SimulationMetrics
|
SimulationMetrics with success/failure statistics. |
max_drawdown_distribution¶
max_drawdown_distribution(wealth_history)
¶
Compute per-path maximum drawdown and return percentiles.
Maximum drawdown = largest peak-to-trough decline as a fraction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wealth_history
|
ndarray
|
(n_paths, n_steps+1) array of total wealth. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, float]
|
Dict with p5, p25, p50, p75, p95, mean of max drawdown (as fractions). |
Sensitivity Analysis¶
SensitivityResult¶
SensitivityResult
dataclass
¶
Result of perturbing a single parameter.
SensitivityReport¶
SensitivityReport
dataclass
¶
Full report of one-at-a-time sensitivity analysis.
HeatmapResult¶
HeatmapResult
dataclass
¶
Result of a 2D sensitivity grid analysis.
run_sensitivity¶
run_sensitivity(plan, market, policies, sim_config, perturbation_pct=0.1, parameters=None, max_workers=None)
¶
Run OAT sensitivity analysis.
Perturbs each parameter by ±perturbation_pct (or additive for ages) and measures the impact on success probability.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
plan
|
PlanConfig
|
Financial plan configuration. |
required |
market
|
MarketAssumptions
|
Market assumptions. |
required |
policies
|
PolicyBundle
|
Policy bundle. |
required |
sim_config
|
SimulationConfig
|
Simulation config (n_paths capped at 2000 for speed). |
required |
perturbation_pct
|
float
|
Fractional perturbation (default 10%). |
0.1
|
parameters
|
list[str] | None
|
Optional list of parameter names to vary. If None, uses all default parameters. |
None
|
max_workers
|
int | None
|
Maximum number of parallel workers. |
None
|
Returns:
| Type | Description |
|---|---|
SensitivityReport
|
SensitivityReport with per-parameter results. |
run_2d_sensitivity¶
run_2d_sensitivity(plan, market, policies, sim_config, x_param, y_param, x_range, y_range, x_steps=12, y_steps=12, max_workers=None)
¶
Run a 2D grid sensitivity analysis.
Varies two parameters simultaneously and measures success probability across an x_steps x y_steps grid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
plan
|
PlanConfig
|
Financial plan configuration. |
required |
market
|
MarketAssumptions
|
Market assumptions. |
required |
policies
|
PolicyBundle
|
Policy bundle. |
required |
sim_config
|
SimulationConfig
|
Simulation config (n_paths capped at 1000 for speed). |
required |
x_param
|
str
|
Name of the x-axis parameter. |
required |
y_param
|
str
|
Name of the y-axis parameter. |
required |
x_range
|
tuple[float, float]
|
(min, max) range for x parameter. |
required |
y_range
|
tuple[float, float]
|
(min, max) range for y parameter. |
required |
x_steps
|
int
|
Number of grid points along x-axis. |
12
|
y_steps
|
int
|
Number of grid points along y-axis. |
12
|
max_workers
|
int | None
|
Maximum number of parallel workers. |
None
|
Returns:
| Type | Description |
|---|---|
HeatmapResult
|
HeatmapResult with the success probability grid. |
Additional Metrics¶
spending_volatility¶
spending_volatility(spending_history, retirement_step)
¶
Compute per-path spending volatility during retirement.
Volatility = standard deviation of month-over-month spending changes divided by mean spending (coefficient of variation of changes).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spending_history
|
ndarray
|
(n_paths, n_steps) array of monthly spending. |
required |
retirement_step
|
int
|
Step index when retirement begins. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, float]
|
Dict with p50 and mean of spending volatility across paths. |
ruin_by_age¶
ruin_by_age(wealth_history, retirement_step, current_age)
¶
Compute fraction of paths depleted at each age.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wealth_history
|
ndarray
|
(n_paths, n_steps+1) array of total wealth. |
required |
retirement_step
|
int
|
Step index when retirement begins. |
required |
current_age
|
int
|
Starting age. |
required |
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray]
|
Tuple of (ages, ruin_fractions) arrays. |