Sell in May - User Documentation
Overview
Sell in May is a professional market analysis application that helps you understand potential future price behavior of stocks by comparing current patterns to historically similar situations. Unlike simple charting apps, Sell in May is regime-aware—it recognizes that markets behave differently in different conditions and only shows you patterns from similar market environments.
Key Features
- Regime-aware pattern matching from 10+ years of historical data
- Optional AI-powered forecasting with probabilistic scenarios
- Macro-economic context integration (optional FRED data)
- 100% on-device processing for complete privacy
- Works offline after initial data download
- Professional-grade technical analysis tools
Getting Started
First Launch
When you first open Sell in May, the app will:
- Request permission to access the internet (needed to download current market data)
- Begin downloading historical data for popular stocks and indexes
- Set up local storage for caching market data
Note: The initial data download may take a few minutes. Once complete, the app works offline for previously analyzed stocks.
Selecting a Stock
To analyze a stock:
- Tap the search or symbol entry field
- Enter a stock symbol (e.g., AAPL, MSFT, TSLA)
- The app will fetch current and historical data for that stock
- Analysis results will appear automatically
Selecting Market Context
You can also select one or more market indexes (like S&P 500, Nasdaq) to provide context for regime detection. The app uses these to understand the broader market environment.
Analyzing Stocks
What the App Does
When you select a stock, Sell in May:
- Detects the current market regime - Classifies volatility, trend, and risk sentiment
- Finds similar historical patterns - Searches 30+ years of data for price curves that look similar under comparable market conditions
- Generates probabilistic forecasts - Shows you what happened after those similar patterns, giving you a range of possible outcomes
- Provides confidence metrics - Tells you how reliable the matches are
Understanding the Analysis View
The main analysis screen shows:
- Current Price Chart - Recent price movement of the selected stock
- Market Regime Badge - Current market conditions (volatility, trend, sentiment)
- Pattern Matches - Historical patterns that are similar to the current situation
- Forecast Scenarios - Probabilistic outcomes showing possible future price movements
- Confidence Metrics - How reliable the analysis is
Understanding Results
Pattern Matches
Pattern matches show you historical price curves that are similar to the current situation. Each match includes:
- Similarity Score - How closely the historical pattern matches (higher is better)
- Date Range - When this pattern occurred historically
- Forward Outcome - What happened to the price after this pattern
- Regime Match - Whether the market regime was similar
Tip: Patterns with similar market regimes are more relevant. The app gives these patterns a similarity boost.
Probabilistic Forecasts
Instead of giving you a single prediction, Sell in May shows you a range of possible outcomes:
- Return Percentiles - 10th, 25th, median, 75th, and 90th percentile outcomes
- Confidence Intervals - The range where most outcomes are likely to fall
- Downside Risk - Probability of significant losses
- Expected Volatility - How much price movement to expect
Example: If the forecast shows:
• 25th percentile: -5% (25% chance of losing 5% or more)
• Median: +3% (50% chance of gaining 3% or more)
• 75th percentile: +8% (25% chance of gaining 8% or more)
This means there's a 50% chance of gains between -5% and +8%, with the most likely outcome around +3%.
Confidence Metrics
The app provides several confidence indicators:
- Match Quality - How similar the historical patterns are
- Regime Consistency - How many matches come from similar market regimes
- Sample Size - How many historical patterns were found
Important: Higher confidence doesn't guarantee accuracy. Markets are unpredictable, and past performance doesn't guarantee future results. Always use this as one tool among many in your investment research.
Market Regime Detection
Sell in May automatically classifies the current market environment across three dimensions:
Volatility
- Low - Markets are calm, VIX typically below 15
- Medium - Normal market fluctuations, VIX 15-25
- High - Elevated uncertainty, VIX above 25
Trend
- Trending - Clear upward or downward price movement
- Mean-Reverting - Prices oscillating around a central value
- Neutral - No clear trend pattern
Risk Sentiment
- Risk-On - Investors are optimistic, buying riskier assets
- Risk-Off - Investors are cautious, seeking safety
- Neutral - Balanced sentiment
Why This Matters: Markets behave very differently in high volatility, risk-off environments versus low volatility, risk-on environments. By matching patterns from similar regimes, the app provides more relevant historical comparisons.
Macro-Economic Context (Optional)
Sell in May can integrate Federal Reserve economic data to provide deeper context about the broader economy. This feature is optional and requires a free FRED API key.
What is FRED?
FRED (Federal Reserve Economic Data) is a database maintained by the Federal Reserve Bank of St. Louis containing thousands of economic indicators. When enabled, Sell in May uses this data to:
- Classify the macro-economic regime (Expansion, Slowdown, Recession, Recovery, Stagflation)
- Calculate recession probability
- Boost similarity scores for patterns from similar economic conditions
Setting Up FRED Integration
- Get a free API key from fred.stlouisfed.org
- Open Sell in May Settings
- Enter your FRED API key
- The app will begin downloading economic indicators
Note: The app works perfectly without a FRED API key. You'll still get regime detection based on market volatility (VIX), but without the additional macro-economic context.
Economic Indicators Used
When FRED is enabled, the app tracks:
- Interest rates (Federal Funds Rate, Treasury yields)
- Yield curve spread (10-year minus 2-year Treasury)
- Credit spreads (High yield, TED spread)
- Inflation metrics (CPI, breakeven rates)
- Economic growth (Unemployment, consumer sentiment)
Macro Regimes
The app classifies the economy into five regimes:
- Expansion - Healthy economic growth
- Slowdown - Growth decelerating
- Recession - Economic contraction
- Recovery - Improving from recession
- Stagflation - High inflation with slow growth (rare)
Settings & Configuration
Analysis Parameters
Sell in May offers 20+ configurable parameters to customize your analysis:
- Pattern Lookback Period - How far back to search for patterns
- Similarity Threshold - Minimum similarity score for matches
- Number of Matches - How many historical patterns to show
- Forecast Horizons - Time periods for predictions (5, 10, 20 days)
- Regime Sensitivity - How strictly to filter by market regime
Data Refresh
You can manually refresh market data or configure automatic background updates. The app caches data locally, so you can analyze stocks offline after the initial download.
Display Options
- Dark mode toggle
- Chart style preferences
- Confidence metric display options
Privacy & Data
🔒 Complete Privacy
All analysis runs on your device. Your data never leaves your iPhone.
- No cloud backend
- No user accounts
- No data collection
- No tracking or analytics
- No sharing with third parties
What Data is Stored?
The app only stores:
- Market data - Stock prices and economic indicators (cached locally)
- Your settings - Analysis parameters and preferences (stored on device)
The app does not store:
- Your stock selections or watchlists
- Your analysis history
- Any personal information
- Any usage data
Internet Usage
The app only uses the internet to:
- Download current market data from Yahoo Finance, FRED, or Stooq
- Update historical price data
Once data is downloaded, the app works completely offline for previously analyzed stocks.
Data Sources
Market data comes from free, public APIs:
- Yahoo Finance - Primary source for stock prices
- FRED - Economic indicators (optional, requires API key)
- Stooq - Fallback for extended historical data