grynn-fplot 0.3.2__tar.gz → 0.3.3__tar.gz

{grynn_fplot-0.3.2 → grynn_fplot-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grynn-fplot
-Version: 0.3.2
+Version: 0.3.3
 Summary: CLI tool for plotting financial data and analyzing options
 Project-URL: Homepage, https://github.com/Grynn/grynn_cli_fplot
 Project-URL: Issues, https://github.com/Grynn/grynn_cli_fplot/issues
@@ -23,6 +23,7 @@ Requires-Dist: grynn-pylib
 Requires-Dist: ipywidgets>=8.1.5
 Requires-Dist: matplotlib>=3.9.2
 Requires-Dist: mplcursors~=0.5.3
+Requires-Dist: mplfinance>=0.12.9
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: scikit-learn>=1.6.1
 Requires-Dist: tabulate>=0.9.0
@@ -106,16 +107,25 @@ Examples:
 - `fplot AAPL --call --filter "dte>10, dte<50"`  # 10-50 days to expiry
 - `fplot AAPL --call --filter "dte>1y"`  # Options with 1+ year to expiry
 
-The options output includes pricing and return metrics:
+The options output includes pricing, return metrics, implied leverage, and efficiency:
 ```
-AAPL 225C 35DTE ($5.25, 18.5%)
-AAPL 230C 35DTE ($3.10, 25.2%)
-AAPL 235C 35DTE ($1.85, 35.1%)
+AAPL 225C 35DTE ($5.25, 18.5%, 19.0x, eff:45)
+AAPL 230C 35DTE ($3.10, 25.2%, 32.3x, eff:78)
+AAPL 235C 35DTE ($1.85, 35.1%, 54.1x, eff:92)
 ```
 
-Format: `TICKER STRIKE[C|P] DAYS_TO_EXPIRY (price, return_metric)`
+Format: `TICKER STRIKE[C|P] DAYS_TO_EXPIRY (price, return_metric, leverage, eff:percentile)`
 - For calls: return_metric is CAGR to breakeven
 - For puts: return_metric is annualized return
+- Leverage: Implied leverage (Ω = Δ × S/O) where Δ is Black-Scholes delta, S is spot price, O is option price
+  - Delta calculated using actual implied volatility from Yahoo Finance
+  - Shows "N/A" if implied volatility is not available
+  - Shows the percentage change in option value for a 1% change in stock price
+  - Example: 10x leverage means a 1% stock move results in ~10% option move
+- Efficiency: Percentile rank (0-100) of leverage/CAGR ratio
+  - Higher = better (high leverage with low required stock movement)
+  - 80+ = top 20% most efficient options
+  - Shows "N/A" if leverage or return unavailable
 
 **Expiry Filtering Options:**
 - `--max <time>`: Filter to show only options expiring within the specified time
@@ -144,6 +154,8 @@ The `--filter` option supports complex filter expressions with logical operators
   - `return`, `ret`, `ar`: Return metric (CAGR for calls, annualized return for puts) - all aliases work
   - `strike_pct`, `sp`: Strike percentage above/below spot (positive = above spot, negative = below spot)
   - `lt_days`: Days since last trade (useful for filtering stale options)
+  - `leverage`, `lev`: Implied leverage (Ω = Δ × S/O, using Black-Scholes delta)
+  - `efficiency`, `eff`: Efficiency percentile (leverage/CAGR ratio, 0-100 scale)
 
 - **Examples:**
   - `--filter "dte>300"` - Options with more than 300 days to expiry
@@ -154,6 +166,10 @@ The `--filter` option supports complex filter expressions with logical operators
   - `--filter "volume>=100"` - High volume options
   - `--filter "lt_days<=7"` - Options traded within last 7 days
   - `--filter "ar>50"` - Annualized return > 50%
+  - `--filter "leverage>10"` - High leverage options (10x or more)
+  - `--filter "lev>5, lev<20"` - Moderate leverage options (5x-20x)
+  - `--filter "efficiency>80"` - Top 20% most efficient options
+  - `--filter "eff>60, dte<60"` - Above-average efficiency with <60 days to expiry
 
 - **Time Values:**
   - DTE-style expressions: `1y` (365 days), `6m` (180 days), `2w` (14 days)
@@ -164,3 +180,9 @@ The `--filter` option supports complex filter expressions with logical operators
     - `--filter "lt_days<=7"` - Options traded in the last week
 
 Options data is cached for 1 hour to improve performance and reduce API calls.
+
+## TODO
+
+- fplot --call | fzf lets you select a call; once a call is selected it should be possible to plot a chart for it (yfinance provides price history for option identifiers)
+- need more examples of usage with fzf to pick a call
+- use grynn_pylib to download options (does it have identifiers that can be used to fetch price history?)

{grynn_fplot-0.3.2 → grynn_fplot-0.3.3}/README.md

@@ -68,16 +68,25 @@ Examples:
 - `fplot AAPL --call --filter "dte>10, dte<50"`  # 10-50 days to expiry
 - `fplot AAPL --call --filter "dte>1y"`  # Options with 1+ year to expiry
 
-The options output includes pricing and return metrics:
+The options output includes pricing, return metrics, implied leverage, and efficiency:
 ```
-AAPL 225C 35DTE ($5.25, 18.5%)
-AAPL 230C 35DTE ($3.10, 25.2%)
-AAPL 235C 35DTE ($1.85, 35.1%)
+AAPL 225C 35DTE ($5.25, 18.5%, 19.0x, eff:45)
+AAPL 230C 35DTE ($3.10, 25.2%, 32.3x, eff:78)
+AAPL 235C 35DTE ($1.85, 35.1%, 54.1x, eff:92)
 ```
 
-Format: `TICKER STRIKE[C|P] DAYS_TO_EXPIRY (price, return_metric)`
+Format: `TICKER STRIKE[C|P] DAYS_TO_EXPIRY (price, return_metric, leverage, eff:percentile)`
 - For calls: return_metric is CAGR to breakeven
 - For puts: return_metric is annualized return
+- Leverage: Implied leverage (Ω = Δ × S/O) where Δ is Black-Scholes delta, S is spot price, O is option price
+  - Delta calculated using actual implied volatility from Yahoo Finance
+  - Shows "N/A" if implied volatility is not available
+  - Shows the percentage change in option value for a 1% change in stock price
+  - Example: 10x leverage means a 1% stock move results in ~10% option move
+- Efficiency: Percentile rank (0-100) of leverage/CAGR ratio
+  - Higher = better (high leverage with low required stock movement)
+  - 80+ = top 20% most efficient options
+  - Shows "N/A" if leverage or return unavailable
 
 **Expiry Filtering Options:**
 - `--max <time>`: Filter to show only options expiring within the specified time
@@ -106,6 +115,8 @@ The `--filter` option supports complex filter expressions with logical operators
   - `return`, `ret`, `ar`: Return metric (CAGR for calls, annualized return for puts) - all aliases work
   - `strike_pct`, `sp`: Strike percentage above/below spot (positive = above spot, negative = below spot)
   - `lt_days`: Days since last trade (useful for filtering stale options)
+  - `leverage`, `lev`: Implied leverage (Ω = Δ × S/O, using Black-Scholes delta)
+  - `efficiency`, `eff`: Efficiency percentile (leverage/CAGR ratio, 0-100 scale)
 
 - **Examples:**
   - `--filter "dte>300"` - Options with more than 300 days to expiry
@@ -116,6 +127,10 @@ The `--filter` option supports complex filter expressions with logical operators
   - `--filter "volume>=100"` - High volume options
   - `--filter "lt_days<=7"` - Options traded within last 7 days
   - `--filter "ar>50"` - Annualized return > 50%
+  - `--filter "leverage>10"` - High leverage options (10x or more)
+  - `--filter "lev>5, lev<20"` - Moderate leverage options (5x-20x)
+  - `--filter "efficiency>80"` - Top 20% most efficient options
+  - `--filter "eff>60, dte<60"` - Above-average efficiency with <60 days to expiry
 
 - **Time Values:**
   - DTE-style expressions: `1y` (365 days), `6m` (180 days), `2w` (14 days)
@@ -126,3 +141,9 @@ The `--filter` option supports complex filter expressions with logical operators
     - `--filter "lt_days<=7"` - Options traded in the last week
 
 Options data is cached for 1 hour to improve performance and reduce API calls.
+
+## TODO
+
+- fplot --call | fzf lets you select a call; once a call is selected it should be possible to plot a chart for it (yfinance provides price history for option identifiers)
+- need more examples of usage with fzf to pick a call
+- use grynn_pylib to download options (does it have identifiers that can be used to fetch price history?)

{grynn_fplot-0.3.2 → grynn_fplot-0.3.3/docs}/FILTER_DESIGN.md

@@ -138,11 +138,11 @@ The `evaluate_filter()` function in `grynn_fplot/core.py` evaluates a filter AST
 ```python
 def evaluate_filter(filter_ast: dict, data: dict) -> bool:
     """Evaluate a filter AST against data.
-    
+
     Args:
         filter_ast: Parsed filter AST
         data: Dictionary with option data
-        
+
     Returns:
         True if data passes filter, False otherwise
     """

{grynn_fplot-0.3.2 → grynn_fplot-0.3.3}/grynn_fplot/cli.py

@@ -7,6 +7,7 @@ import click
 import matplotlib.pyplot as plt
 import mplcursors
 import numpy as np
+import mplfinance as mpf
 from grynn_pylib.finance.timeseries import rolling_cagr
 from loguru import logger
 from tabulate import tabulate
@@ -16,6 +17,7 @@ from grynn_fplot.core import (
     calculate_cagr,
     calculate_drawdowns,
     download_ticker_data,
+    download_ohlcv_data,
     normalize_prices,
     parse_start_date,
     format_options_for_display,
@@ -31,7 +33,7 @@ except importlib.metadata.PackageNotFoundError:
 @click.command()
 @click.option("--since", type=str, default=None, help="Start date for data (e.g., '1y', '6m', '2023-01-01')")
 @click.option("--interval", type=str, default="1d", help="Data interval (1d, 1wk, 1mo)")
-@click.argument("ticker", type=str, nargs=1, required=False)
+@click.argument("ticker", type=str, nargs=-1, required=False)
 @click.option("--version", "-v", is_flag=True, help="Show version and exit")
 @click.option("--debug", is_flag=True, help="Enable debug mode")
 @click.option("--call", is_flag=True, help="List all available call options for the ticker")
@@ -86,6 +88,24 @@ def display_plot(
 
     Examples:
     \b
+    # Single ticker
+    fplot AAPL
+    
+    # Multiple tickers (space-separated)
+    fplot AAPL TSLA MSFT
+    
+    # Comma-separated tickers
+    fplot AAPL,TSLA
+    
+    # Division operations
+    fplot AAPL/XLK
+    
+    # Mixed inputs
+    fplot AAPL AAPL/XLK TW.L
+    
+    # Quoted strings with commas
+    fplot "AAPL, TSLA"
+    
     # List all AAPL call options (default: 6 months max)
     fplot AAPL --call
 
@@ -109,23 +129,33 @@ def display_plot(
         print(f"fplot {__version__}")
         return
 
-    # Show filter help if requested
+# Show filter help if requested
     if filter_help:
         from grynn_fplot.filter_parser import get_filter_help
 
         print(get_filter_help())
         return
 
+    # Convert ticker tuple to list (Click's variadic arguments return a tuple)
+    ticker_list = list(ticker) if ticker else []
     # Launch web interface if --web flag is used
     if web:
-        launch_web_interface(ticker, since, interval, port, host, no_browser, debug)
+        # For web interface, join tickers back into a string
+        ticker_str = ','.join(ticker_list) if ticker_list else None
+        launch_web_interface(ticker_str, since, interval, port, host, no_browser, debug)
         return
 
     # CLI mode - require ticker
-    if not ticker:
+    if not ticker_list:
         click.echo(
-            "Error: Missing argument 'TICKER'. Please provide a ticker symbol or symbols as a comma separated list."
+            "Error: Missing argument 'TICKER'. Please provide ticker symbol(s)."
         )
+        click.echo("Examples:")
+        click.echo("  fplot AAPL")
+        click.echo("  fplot AAPL TSLA")
+        click.echo("  fplot AAPL,TSLA")
+        click.echo("  fplot AAPL/XLK")
+        click.echo('  fplot "AAPL, TSLA"')
         click.echo("Hint: Use --web or -w to launch the interactive web interface.")
         return
 
@@ -176,8 +206,10 @@ def display_plot(
 
     # Handle options listing
     if call:
+        # For options, use the first ticker only (options only work with single ticker)
+        ticker_for_options = ticker_list[0] if ticker_list else ""
         options_list = format_options_for_display(
-            ticker,
+            ticker_for_options,
             "calls",
             max_expiry=use_max_expiry,
             min_dte=parsed_min_dte,
@@ -185,7 +217,7 @@ def display_plot(
             filter_ast=parsed_filter,
         )
         if not options_list:
-            click.echo(f"No call options found for {ticker.upper()}")
+            click.echo(f"No call options found for {ticker_for_options.upper()}")
             return
 
         for option in options_list:
@@ -193,8 +225,10 @@ def display_plot(
         return
 
     if put:
+        # For options, use the first ticker only (options only work with single ticker)
+        ticker_for_options = ticker_list[0] if ticker_list else ""
         options_list = format_options_for_display(
-            ticker,
+            ticker_for_options,
             "puts",
             max_expiry=use_max_expiry,
             min_dte=parsed_min_dte,
@@ -202,7 +236,7 @@ def display_plot(
             filter_ast=parsed_filter,
         )
         if not options_list:
-            click.echo(f"No put options found for {ticker.upper()}")
+            click.echo(f"No put options found for {ticker_for_options.upper()}")
             return
 
         for option in options_list:
@@ -210,7 +244,7 @@ def display_plot(
         return
 
     # Continue with original CLI plotting logic
-    display_cli_plot(ticker, since, interval, debug)
+    display_cli_plot(ticker_list, since, interval, debug)
 
 
 def launch_web_interface(ticker, since, interval, port, host, no_browser, debug):
@@ -314,8 +348,124 @@ def launch_web_interface(ticker, since, interval, port, host, no_browser, debug)
         return
 
 
+def display_candlestick_plot(ticker, since, interval, debug):
+    """Display candlestick plot with volume and SMAs for a single ticker"""
+    from dateutil.relativedelta import relativedelta
+    
+    requested_since = parse_start_date(since)
+    
+    # Always fetch 3 years of data to ensure we can compute 200-day SMA
+    # even if the user requested a shorter timeframe
+    fetch_since = datetime.now() - relativedelta(years=3)
+    
+    # Download OHLCV data (fetch 3 years)
+    df_full = download_ohlcv_data(ticker, fetch_since, interval)
+    if df_full.empty:
+        print(f"No data found for {ticker}.")
+        return
+    
+    # Calculate SMAs on the full dataset (3 years)
+    sma_50 = df_full['Close'].rolling(window=50).mean()
+    sma_200 = df_full['Close'].rolling(window=200).mean()
+    
+    # Filter to the requested timeframe for display
+    if requested_since is not None:
+        df = df_full[df_full.index >= requested_since]
+        sma_50 = sma_50[sma_50.index >= requested_since]
+        sma_200 = sma_200[sma_200.index >= requested_since]
+    else:
+        df = df_full
+    
+    if df.empty:
+        print(f"No data found for {ticker} in the requested timeframe.")
+        return
+    
+    print(f"Generating candlestick plot for {ticker} since {requested_since.date() if requested_since else 'max'}. Interval: {interval}")
+    
+    if debug:
+        print(f"Data for {ticker}:")
+        print(f"Full dataset: {len(df_full)} rows, Display dataset: {len(df)} rows")
+        print(df.head())
+        temp_file = tempfile.NamedTemporaryFile(suffix=".csv", delete=False)
+        df.to_csv(temp_file.name)
+        print(f"Data saved to temporary file: {temp_file.name}")
+    
+    # Create additional plots list for SMAs
+    add_plots = []
+    
+    # Add 50-day SMA if we have enough data
+    if not sma_50.isna().all():
+        add_plots.append(mpf.make_addplot(sma_50, color='orange', width=1.5, label='50-day SMA'))
+    
+    # Add 200-day SMA if we have enough data
+    if not sma_200.isna().all():
+        add_plots.append(mpf.make_addplot(sma_200, color='red', width=1.5, label='200-day SMA'))
+    
+    # Configure mplfinance style
+    mc = mpf.make_marketcolors(
+        up='green', down='red',
+        wick={'up': 'green', 'down': 'red'},
+        edge={'up': 'green', 'down': 'red'},
+        volume={'up': 'green', 'down': 'red'}
+    )
+    s = mpf.make_mpf_style(marketcolors=mc, gridstyle=':', y_on_right=False)
+    
+    # Create the plot
+    fig, axes = mpf.plot(
+        df,
+        type='candle',
+        style=s,
+        volume=True,
+        addplot=add_plots if add_plots else None,
+        title=f"{ticker} - Candlestick Chart",
+        ylabel='Price',
+        ylabel_lower='Volume',
+        figsize=(16, 10),
+        datetime_format='%Y-%m-%d',
+        xrotation=15,
+        returnfig=True,
+        warn_too_much_data=1000  # Suppress warning for large datasets
+    )
+    
+    # Add legend for SMAs if they exist
+    if add_plots:
+        ax = axes[0]  # Main price axis
+        # Create custom legend entries
+        from matplotlib.lines import Line2D
+        legend_elements = [
+            Line2D([0], [0], color='green', lw=2, label='Up Day'),
+            Line2D([0], [0], color='red', lw=2, label='Down Day'),
+        ]
+        if not sma_50.isna().all():
+            legend_elements.append(Line2D([0], [0], color='orange', lw=1.5, label='50-day SMA'))
+        if not sma_200.isna().all():
+            legend_elements.append(Line2D([0], [0], color='red', lw=1.5, label='200-day SMA'))
+        
+        ax.legend(handles=legend_elements, loc='best')
+    
+    plt.show()
+
+
 def display_cli_plot(ticker, since, interval, debug):
     """Display plot using matplotlib (original CLI functionality)"""
+    from grynn_fplot.core import parse_ticker_input
+    
+    # Parse ticker input to understand what we're dealing with
+    parsed_tickers = parse_ticker_input(ticker)
+    
+    # Check if this is a single ticker scenario (should use candlestick)
+    # Single ticker means:
+    # 1. No division operators in any ticker
+    # 2. Exactly one ticker provided (not counting SPY which is auto-added)
+    has_division = any('/' in t for t in parsed_tickers)
+    ticker_count = len(parsed_tickers)
+    
+    # Route to candlestick chart for single ticker without division
+    if not has_division and ticker_count == 1:
+        display_candlestick_plot(parsed_tickers[0], since, interval, debug)
+        return
+    
+    # Otherwise, continue with existing line chart logic for multi-ticker or division
     since = parse_start_date(since)
 
     # Download and prepare data