analyze_quantitative
Build and train linear factor models to compute portfolio betas, factor exposures, and per-asset R². Adjust the rolling window to detect genuine beta shifts versus noise.
Instructions
Build and train linear factor models for a portfolio in one step (creates models → trains → computes betas). This is the starting point for Moment (linear) analysis. Requires conditioning_set_id (the market drivers — get one from list_feature_set_templates or create_feature_set). Uses a two-layer architecture: thematic factors (conditioning_set_id) + optional baseline factors (baseline_mode='us' absorbs market/value/growth variance via real-time ETF proxies before thematic factors). Pass either portfolio_id or tickers directly (auto-creates portfolio with equal weights). Returns: factor exposures (betas), per-asset R² (in-sample goodness-of-fit — tells you how linear the relationship actually is for the given window), rolling_window used, factor_last_date (effective beta date — may be truncated if a factor has stale data), and data_truncated_by (which factors caused truncation).
Important: there is NO regime-conditional or 'calm vs stress' beta API. If a user asks for regime decomposition, do NOT invent it — the right substitute is to RE-RUN this tool with a shorter rolling_window (e.g. 90 days vs the 252-day default) and compare the betas to the long-window fit. Where (a) a beta shifted meaningfully AND (b) R² stayed reasonable in the short window, that's a real shift to talk about. Where R² collapsed in the short window, the apparent shift is noise from thin degrees of freedom — say so explicitly to the user. Do NOT pick rolling_window < 90 unless you have very few factors: each per-asset regression has (n_factors + n_baseline_etfs) RHS variables, and you need at least ~10 obs per parameter for stable betas (so rolling_window=90 supports up to ~9 RHS variables, rolling_window=60 supports ~6).
Low R² (e.g. < 0.2) suggests nonlinear dynamics or missing factors — flag the asset, don't claim a precise beta decomposition. R² in this Moment model is per-asset (each asset gets its own regression on the conditioning set), so a low R² for one name doesn't impeach the others. Next step: call compute_returns with the simulation_batch_id to run what-if stress tests.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tickers | No | Tickers to analyze (e.g. ['AAPL', 'MSFT']). Auto-creates a portfolio if portfolio_id is not given. | |
| weights | No | Optional weights for tickers (must sum to 1.0). Defaults to equal weights. | |
| nonlinear | No | Also fit nonlinear factor exposure model on top of linear betas, producing sensitivity curves. Requires Pro+ tier. Default True (runs if tier allows). | |
| portfolio_id | No | UUID of an existing portfolio. If omitted, provide tickers instead. | |
| baseline_mode | No | Baseline factor orthogonalization region. ETF-based (real-time): 'us', 'global', 'developed_ex_us', 'europe', 'japan'. Legacy FF5 (~2mo lag): 'us_ff5', 'global_ff5'. Set 'none' or omit to skip baseline. | |
| rolling_window | No | Rolling window size in trading days for beta estimation (default 252 = ~1 year). Smaller = more responsive to recent regime changes, larger = more stable. | |
| conditioning_set_id | Yes | UUID of the thematic conditioning set (from list_feature_set_templates or create_feature_set) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |