How chrislernunes/nautilus works
1. Overall shape
Nautilus is a local research platform, not a service backend. The main execution path is: market/macro data ingestion → feature engineering → 5-state HMM regime inference → signal generation/backtesting → Streamlit dashboard visualization and export.
2. Primary entry point
The dashboard at src/nautilus/dashboard/regime_dashboard.py is the main application entry point. It orchestrates data loading, model fitting, signal calculation, plots, tables, and CSV exports in one interactive Streamlit UI.
3. Data sources and persistence boundaries
The system combines:
- Nifty 50 and US market series from yfinance
- Bundled local CSVs for India 10Y yield and RBI repo rate
- Local Parquet cache under data/cache/ for downloaded/processed market data
This creates a clear split between external data acquisition and repeatable local analysis.
4. ETL layer
src/nautilus/etl/loader.py handles price download and caching, while src/nautilus/etl/macro.py builds the macro feature set. This layer is responsible for aligning heterogeneous series on a common trading calendar and preparing model-ready inputs.
5. Macro feature engineering
The macro pipeline folds Indian rates and bond data into regime features such as yield changes, yield spread, RBI easing flags, and moving-average ratios. The README indicates the HMM consumes a wide feature vector: realized volatility, returns, vol-of-vol, drawdown, 10Y yield delta, spread, repo flag, and DMA ratio.
6. Regime modeling subsystem
src/nautilus/strategies/regime.py is the core analytics module. It fits a 5-state Gaussian Hidden Markov Model using hmmlearn, produces posterior regime probabilities, assigns dominant states, and provides Markov forward forecasts. The states are interpreted as market regimes like Bull Quiet, Bull Volatile, Neutral, Stress, and Panic.
7. Signal generation subsystem
src/nautilus/strategies/momentum.py provides the baseline directional signal logic, centered on moving-average / price-above-MA behavior. The regime strategy then overlays a hard gate on top of this base signal, reducing or zeroing exposure depending on the inferred HMM state.
8. Backtest engine
src/nautilus/backtests/engine.py evaluates MA vs regime-filtered strategies, applies transaction costs, and computes equity curves and performance metrics. The tests in tests/test_engine.py indicate this module is treated as a distinct, testable computational boundary separate from the dashboard.
9. Decision layering
The strategy stack has two levels of control:
- a continuous “soft Kelly” style signal, smoothed with EWM(5)
- a discrete hard regime gate shifted by one day to avoid look-ahead
This means the final backtest signal is not just a model output; it is the composition of momentum plus regime-based capital allocation.
10. Dashboard visualization layer
The Streamlit app presents multiple synchronized panels: regime shading on price charts, posterior probability stacks, Markov forecast paths, macro panels, volatility and drawdown views, attribution tables, and backtest comparison charts. The dashboard is a read-only analytical layer over the model and backtest outputs rather than a separate computation engine.
11. US macro overlay
The US monitor is a parallel data track within the same dashboard, using S&P 500, US 10Y–3M spread, and Fed Funds Rate. Its shared-x alignment and inversion shading are important because they show the repo is built for cross-market regime comparison, not just India-only analysis.
12. Configuration and package boundaries
src/nautilus/config.py centralizes paths, tickers, and model defaults, while src/nautilus/__init__.py marks the package version. The package is organized by concern: ETL, strategies, backtests, dashboard, with data stored outside the code under data/.
13. Operational model
This repository is designed for interactive research on a local machine. There is no evidence of a database, message bus, or server-side orchestration layer; the main operational dependencies are Streamlit for UI, Parquet/CSV on disk for storage, and external market data APIs for refreshes.
14. What an architecture diagram should show
A good diagram would place external data sources on the left, the ETL/cache layer in the middle, then split into two downstream paths: (a) regime/model/signal/backtest computation and (b) Streamlit dashboard visualization/export. The shared dependency between those paths is the feature-engineered time series and regime outputs.
Main entry points: regime_dashboard.py Regime dashboard · loader.py Market loader · macro.py Macro features · momentum.py Momentum signal
Components 16
External sources
Market and macro inputs pulled from APIs and bundled local CSV data.
- Market APIs · Nifty 50 and US market series fetched from yfinance.
- Macro CSVs · Bundled India 10Y yield and RBI repo rate files.
data/india_10y_yield.csv - Parquet cache · Repeatable cached market and macro data stored on disk.
data/cache/_caret_NSEI.parquet
Core analysis
ETL, feature engineering, regime inference, signal logic, and backtesting.
- Config · Centralized paths, tickers, and defaults.
src/nautilus/config.py - Market loader · Downloads price data and manages local caching.
src/nautilus/etl/loader.py - Macro features · Aligns macro series and engineers regime features.
src/nautilus/etl/macro.py - Momentum signal · Baseline moving-average / price-above-MA directional signal.
src/nautilus/strategies/momentum.py - Regime model · Fits the 5-state Gaussian HMM and derives regime probabilities and forecasts.
src/nautilus/strategies/regime.py - Backtest engine · Runs MA vs regime-filtered strategies with costs and metrics.
src/nautilus/backtests/engine.py - Package root · Nautilus package boundary and version marker.
src/nautilus/__init__.py - Engine tests · Test coverage for the backtest engine as a separate computational unit.
tests/test_engine.py
Dashboard
Interactive Streamlit analysis and export layer.
- Regime dashboard · Main entry point coordinating model runs, charts, tables, and CSV export.
src/nautilus/dashboard/regime_dashboard.py - Price views · Regime shading and price-based chart panels.
- Probabilities · Posterior state stacks and Markov forecast visualizations.
- Macro views · Macro, volatility, drawdown, and cross-market comparison panels.
- Performance · Backtest comparison charts and attribution tables.
Connections 21
- Market APIs → Market loader: market data · External market series are fetched for ingestion.
- Macro CSVs → Macro features: macro inputs · Bundled CSVs supply India yield and repo series.
- Parquet cache → Market loader: cached data · Loader reads and writes local Parquet cache.
- Config → Market loader: paths/defaults · Config provides tickers, paths, and operational defaults.
- Config → Macro features: paths/defaults · Config supports feature-building inputs and conventions.
- Market loader → Macro features: aligned series · Loaded market data feeds feature engineering.
- Market loader → Momentum signal: price series · Momentum logic consumes cleaned price history.
- Macro features → Regime model: feature vector · Engineered macro and market features drive HMM inference.
- Macro features → Regime dashboard: macro panels · Dashboard renders macro outputs and comparison views.
- Momentum signal → Regime model: base signal · Regime logic overlays gating on top of momentum behavior.
- Regime model → Backtest engine: state signal · Dominant states and probabilities shape the trading regime filter.
- Momentum signal → Backtest engine: baseline strategy · Backtests compare the raw momentum benchmark.
- Backtest engine → Regime dashboard: metrics/equity · Performance outputs are visualized in the dashboard.
- Regime model → Regime dashboard: regime outputs · Posterior probabilities, forecasts, and state labels feed the UI.
- Momentum signal → Regime dashboard: signals · Signal series support charts and export.
- Regime dashboard → Price views: renders · Main app composes price and regime shading panels.
- Regime dashboard → Probabilities: renders · Main app composes posterior and forecast panels.
- Regime dashboard → Macro views: renders · Main app composes macro and cross-market panels.
- Regime dashboard → Performance: renders · Main app composes backtest comparison and attribution panels.
- Engine tests → Backtest engine: validates · Tests treat the engine as a distinct computational boundary.
- Package root → Config: package boundary · Package root anchors shared modules and versioning.