What factor model does the ETF optimizer use?

We use a Fama-French 5-factor model plus momentum (Mkt-RF, SMB, HML, RMW, CMA, Mom) and estimate ETF factor exposures via rolling OLS regression. The covariance matrix is reconstructed as Sigma = B * Sigma_f * B' + diag(idiosyncratic variance), annualized from 10-year daily returns.

How does the Black-Litterman model work in the optimizer?

We blend market-equilibrium returns (derived from the covariance matrix) with CAPM views to produce posterior expected returns. This is controlled by feature flags: black_litterman_enabled and black_litterman_view_confidence. Default behavior uses CAPM without blending.

How does the optimizer handle taxes?

The optimizer models per-instrument after-tax returns using security-type classification, qualified-dividend percentages, Treasury state-exemption percentages, muni AMT exposure, and Section 1256 status. Tax-loss harvesting is wash-sale-aware, with substantially-identical risk flags for common index fund pairs.

What tail risk model does the portfolio optimizer use?

The default tail engine is multivariate Student-t (df=6), variance-matched to the covariance matrix. This captures fat tails better than Gaussian (MVN) simulation. An optional tail_distribution=normal parameter reverts to legacy MVN. Stress scenarios are labeled illustrative_sleeve_shock, not historical replay.

Is this investment advice?

No. My ETF Portfolio is a decision-support research tool, not an investment advisor. All outputs carry honesty flags, disclaimers, and methodology citations. The optimizer shows its work so advisors can defend every line item, but portfolio decisions remain the user's responsibility.

What is the difference between distribution yield, SEC yield, and YTM?

Distribution yield reflects past payouts annualized, SEC yield is a standardized 30-day calculation, and yield-to-maturity (YTM) is the forward-looking return if bonds are held to maturity. These three numbers can differ significantly for the same bond ETF. Our engine flags YIELD_DIST_FALLBACK when using distribution yield as a return proxy instead of SEC yield.

How We Model ETF Portfolios — Methodology

Live · FRED + Damodaran

Live CAPM inputs

Risk-free rate from FRED 3M Treasury, equity risk premium from Damodaran's implied FCFE model. Updated live.

Objective
Maximize after-tax utility subject to hard constraints
Risk engine
Factor covariance plus portfolio greeks
Output
Reviewable proposal with audit flags

Model pillars

22 named factors

Factor Covariance

Fama-French 5 (market, size, value, profitability, investment) plus momentum, 5 ETF style factor proxies (quality, min-vol, momentum, value, large-cap value), and 11 GICS sector SPDR proxies (tech, health, financial, energy, industrial, staples, utilities, materials, real estate, comms, discretionary) reconstruct covariance from exposures instead of relying only on noisy pairwise history.

optional · off by default

Black-Litterman

An optional overlay that blends market-implied equilibrium returns with model views. It ships disabled: the default path uses CAPM expected returns directly, without blending. See the model-view note below.

bps-aware objective

After-Tax Utility

Every candidate is converted to after-tax expected return after expense, ordinary income, NIIT, state tax, LTCG, and wrapper treatment.

SLSQP + repairs

Hard Constraints

The solve respects sleeve weights, duration bands, liquidity floors, per-holding caps, muni caps, and wash-sale exclusions.

The math stack

The model turns market data, fund metadata, tax rules, and client constraints into a single audited weight vector.

Layer	Formula	Feeds
Factor exposure regression	`R_i,t = alpha_i + beta_i * F_t + epsilon_i,t`	beta loadings, residual risk, factor attribution
Covariance reconstruction	`Sigma_assets = B * Sigma_factors * B' + D_epsilon`	risk matrix for mean-variance and stress math
Black-Litterman posterior	`E[R] = pi + tau Sigma P' (P tau Sigma P' + Omega)^-1 (Q - P pi)`	shrunk expected returns from equilibrium plus views — optional overlay, off by default (default path uses CAPM views directly)
Return shrinkage	`mu_i <- sleeve_mean + (1 - delta)(mu_i - sleeve_mean), delta=0.5`	regularizes after-tax returns within each sleeve so noise-level input error can't reshuffle the book (on by default)
Tax-aware utility	`score(w) = w' mu_after_tax - lambda w' Sigma w - costs - penalties`	weights optimized for client-specific after-tax tradeoffs
Tax drag	`drag_i = yield_i * effective_rate_i + wrapper_adjustments_i`	ordinary, NIIT, state, muni, Treasury, and LTCG treatment
Concentration (ENB)	`ENB = 1 / sum(p_i^2) where p_i = PC variance share`	PCA effective number of bets — prevents VOO+VTI+QQQ from looking diversified
Parametric portfolio risk simulation	`N multivariate Student-t (df=6) draws under model μ,Σ (conservative default)`	VaR/CVaR + multi-year path DD; calibration JSON is advisory until production_ready; not plan MC
Cash / FI horizon glide	`gross = y * locked(dur,H) + (cash_neutral + term_premium) * (1 - locked)`	Short FI and BOXX share the same rate anchor; tax character differs after glide
FoF complexity scorecard	`matched-risk after-tax edge vs AOR-class (or income baseline); ≥25 bps full path`	fof_scorecard only — implementation always multi-ETF (never “use AOR” CALL)
Efficient frontier sweep	`solve for max after-tax return at each equity grid point`	Pareto boundary of feasible stock/bond allocations
Horizon equity glide (optional)	`equity_pct -= max(0, 25 - horizon) * 0.01, floor 20%`	reduces equity for shorter investment horizons when enabled

Constraint system

Constraint	Expression	Why it matters
Full investment	`sum(w_i) = 1`	No unmodeled residual cash unless a cash sleeve is explicit.
Sleeve controls	`min_s <= sum(w_sleeve) <= max_s`	Keeps equity, bond, muni, Treasury, and alternatives in mandate.
Duration bounds	`floor_d <= sum(w_bond * duration_bond) <= cap_d`	Prevents yield chasing by hiding rate risk in long bonds.
Liquidity floor	`sum(w_true_liquidity) >= liquidity_floor`	Requires real cash-like ballast for short-horizon capital.
Concentration caps	`w_i <= cap_i and role_count penalties`	Stops one cheap ticker from swallowing the portfolio.
Wash-sale hygiene	`blocked symbols and substitute-risk pairs excluded`	Keeps tax-loss harvesting assumptions from being fake precision.

Tax treatment matrix

State defaults use the active tax profile. Out-of-state municipal income and fund-specific source breakdowns require review.

Instrument	Federal	NIIT	State	Modeled as
Taxable MMFSWVXX	—	—	—	Ordinary income drag
Treasury ETFUSFR, TFLO	—	—	Exempt	Federal plus NIIT, state exempt
National MuniMEAR, IBMx	Exempt	Exempt	—Check source	Federal tax-free, state source checked
NC Long-MuniNTFIX	Exempt	Exempt	Exempt	In-state tax-exempt income
Deferred LTCG (BOXX)BOXX	—	—	—	LTCG/deferral with suitability flags

Review & validation

Review package

Risk greeks: beta, duration, convexity, credit-spread durationShows what the client actually owns after optimization.
Distribution risk: yield mix, tax buckets, ordinary-vs-LTCG treatmentSeparates headline yield from spendable after-tax return.
Cost model: expense ratio, fee edge, tax drag edge in bpsTurns small ETF differences into comparable annual drag.
Cardinality refinement: iterative position dropping, dust cleanup, role preservationKeeps the portfolio to a defensible position count without violating constraints.

Validation evidence

Golden portfoliosdeterministic: 6 canonical scenarios pinned with +/-1.5% per-position drift gates
CFP scenariosreviewed: hard cases compare model outputs against financial-planning assertions
LifePath efficiency benchmarkpassing: Matched-risk fee/efficiency comparison vs iShares LifePath ETFs (not a claim of superior realized client outcomes). Eval framing: cost and after-tax efficiency at similar equity mix — see evals/lifepath_benchmark_report.md
Stress batteriesmodeled: rate shocks, muni NAV gaps, credit/liquidity pressure, and crisis drawdowns

Model trace

strategies/factors.py
Factor returns, exposures, and covariance reconstruction
strategies/black_litterman.py
Market prior plus model-view posterior expected returns
strategies/unified_allocator.py
Mean-variance utility, constraints, stress, and repairs
services/portfolio_greeks.py
Portfolio greeks, suitability flags, and sensitivity package
tests/test_golden_portfolios.py
Regression harness for model drift across canonical investors
evals/lifepath_benchmark_report.md
Matched-risk benchmark evidence against target-date ETFs

API-only capabilities

These features are available through the REST API but not exposed in the web wizard. They require inputs the UI does not collect.

Feature	Required input	What it does
Tax-loss harvesting	`current_positions with cost basis`	Scans for underwater positions, proposes non-substantially-identical swap partners, values losses at IRC 1211 rates, enforces 30-day wash-sale window with outside-account checking.
Sensitivity analysis	`POST /allocator/sensitivity`	Re-runs the optimizer with expected returns shocked +/-10% and reports weight stability. A stable recommendation is a prerequisite for a defensible allocation.
Foreign tax credit	`foreign_tax_credit_rate`	Reduces effective tax drag on international ETFs by the foreign tax credit rate. UI sends 0.0; API callers can pass the actual rate.
Transition optimization	`current_positions + transition params`	Models the tax cost of moving from current holdings to the target portfolio, amortizes one-time costs over the horizon, and recommends whether to transition now or phase it.

Review before implementation. All allocations are proposals for review. Tax treatment, suitability, liquidity, and fund-specific assumptions still need human verification before client use.

Layer

Formula

Feeds

Factor exposure regression

R_i,t = alpha_i + beta_i * F_t + epsilon_i,t

beta loadings, residual risk, factor attribution

Covariance reconstruction

Sigma_assets = B * Sigma_factors * B' + D_epsilon

risk matrix for mean-variance and stress math

Black-Litterman posterior

E[R] = pi + tau Sigma P' (P tau Sigma P' + Omega)^-1 (Q - P pi)

shrunk expected returns from equilibrium plus views — optional overlay, off by default (default path uses CAPM views directly)

Return shrinkage

mu_i <- sleeve_mean + (1 - delta)(mu_i - sleeve_mean), delta=0.5

regularizes after-tax returns within each sleeve so noise-level input error can't reshuffle the book (on by default)

Tax-aware utility

score(w) = w' mu_after_tax - lambda w' Sigma w - costs - penalties

weights optimized for client-specific after-tax tradeoffs

Tax drag

drag_i = yield_i * effective_rate_i + wrapper_adjustments_i

ordinary, NIIT, state, muni, Treasury, and LTCG treatment

Concentration (ENB)

ENB = 1 / sum(p_i^2) where p_i = PC variance share

PCA effective number of bets — prevents VOO+VTI+QQQ from looking diversified

Parametric portfolio risk simulation

N multivariate Student-t (df=6) draws under model μ,Σ (conservative default)

VaR/CVaR + multi-year path DD; calibration JSON is advisory until production_ready; not plan MC

Cash / FI horizon glide

gross = y * locked(dur,H) + (cash_neutral + term_premium) * (1 - locked)

Short FI and BOXX share the same rate anchor; tax character differs after glide

FoF complexity scorecard

matched-risk after-tax edge vs AOR-class (or income baseline); ≥25 bps full path

fof_scorecard only — implementation always multi-ETF (never “use AOR” CALL)

Efficient frontier sweep

solve for max after-tax return at each equity grid point

Pareto boundary of feasible stock/bond allocations

Horizon equity glide (optional)

equity_pct -= max(0, 25 - horizon) * 0.01, floor 20%

reduces equity for shorter investment horizons when enabled

Constraint

Expression

Why it matters

Full investment

sum(w_i) = 1

No unmodeled residual cash unless a cash sleeve is explicit.

Sleeve controls

min_s <= sum(w_sleeve) <= max_s

Keeps equity, bond, muni, Treasury, and alternatives in mandate.

Duration bounds

floor_d <= sum(w_bond * duration_bond) <= cap_d

Prevents yield chasing by hiding rate risk in long bonds.

Liquidity floor

sum(w_true_liquidity) >= liquidity_floor

Requires real cash-like ballast for short-horizon capital.

Concentration caps

w_i <= cap_i and role_count penalties

Stops one cheap ticker from swallowing the portfolio.

Wash-sale hygiene

blocked symbols and substitute-risk pairs excluded

Keeps tax-loss harvesting assumptions from being fake precision.

Instrument

Federal

NIIT

State

Modeled as

Taxable MMFSWVXX

—

Ordinary income drag

Treasury ETFUSFR, TFLO

—

Exempt

Federal plus NIIT, state exempt

National MuniMEAR, IBMx

Exempt

—Check source

Federal tax-free, state source checked

NC Long-MuniNTFIX

Exempt

In-state tax-exempt income

Deferred LTCG (BOXX)BOXX

—

LTCG/deferral with suitability flags

Feature

Required input

What it does

Tax-loss harvesting

current_positions with cost basis

Scans for underwater positions, proposes non-substantially-identical swap partners, values losses at IRC 1211 rates, enforces 30-day wash-sale window with outside-account checking.

Sensitivity analysis

POST /allocator/sensitivity

Re-runs the optimizer with expected returns shocked +/-10% and reports weight stability. A stable recommendation is a prerequisite for a defensible allocation.

Foreign tax credit

foreign_tax_credit_rate

Reduces effective tax drag on international ETFs by the foreign tax credit rate. UI sends 0.0; API callers can pass the actual rate.

Transition optimization

current_positions + transition params

Models the tax cost of moving from current holdings to the target portfolio, amortizes one-time costs over the horizon, and recommends whether to transition now or phase it.

Live CAPM inputs

Objective

Risk engine

Output

Factor Covariance

Black-Litterman

After-Tax Utility

Hard Constraints

Review package

Validation evidence

Live CAPM inputs

Objective

Risk engine

Output

Factor Covariance

Black-Litterman

After-Tax Utility

Hard Constraints

Review package

Validation evidence