Projections¶
Unified projection interface and scenario comparison.
compare_investment_scenarios¶
Compare three investment scenarios: conservative, moderate, and aggressive.
| Parameter | Type | Default | Description |
|---|---|---|---|
initial_balance_cents |
int | required | Starting balance in cents |
years |
int | 30 |
Number of years to project |
num_simulations |
int | 1000 |
Number of Monte Carlo simulations per scenario |
inflation |
float | 0.0 |
Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, results are in today's purchasing power (real dollars). |
Returns percentile outcomes for each scenario to help with risk/return tradeoffs.
run_projection¶
Run a financial projection with constant or time-varying returns.
| Parameter | Type | Default | Description |
|---|---|---|---|
initial_balance_cents |
int | required | Starting balance in cents |
expected_annual_return |
float | null | Expected annual return (e.g., 0.07 = 7%). Use with annual_volatility and time_horizon_months for constant-return projections. |
annual_volatility |
float | null | Annual volatility/std dev (e.g., 0.15 = 15%). Use with expected_annual_return and time_horizon_months. |
time_horizon_months |
int | null | Number of months to project. Required for constant-return mode. For timeline mode, the horizon is derived from the timeline length. |
return_distribution_timeline |
list | null | List of monthly return distributions for time-varying returns (glide paths). Each entry: {'month': 1, 'return': 0.07, 'volatility': 0.15}. Month indices must be 1-indexed and sequential. Mutually exclusive with expected_annual_return/annual_volatility/time_horizon_months. |
monthly_contribution_cents |
int | 0 |
Fixed monthly contribution in cents. Use negative values for withdrawals. |
method |
string | "closed_form" |
Projection method (closed_form is recommended) |
iterations |
int | 1000 |
Number of Monte Carlo iterations (only used for monte_carlo method) |
seed |
int | null | Random seed for reproducibility |
annual_fee |
float | 0.0 |
Annual fee as decimal (e.g., 0.005 = 0.5%). Not yet supported; reserved for future use. |
inflation |
float | list[float] | 0.0 |
Annual inflation rate as decimal (e.g., 0.03 = 3%). Scalar applied uniformly, or list of annualized rates (one per month of the projection). Adjusts nominal returns to real returns via the Fisher equation. |
percentiles |
list | null | Percentiles to compute (default: [10, 25, 50, 75, 90]). |
Returns file URLs + compact inline summary. Full time series data is written