Add butterfly, iron condor, and covered strategies (#73)

* Add 10 new options strategies: butterflies, iron condors, and covered strategies

New strategies implemented:
- Long/short call butterfly (3-leg)
- Long/short put butterfly (3-leg)
- Iron condor and reverse iron condor (4-leg)
- Iron butterfly and reverse iron butterfly (4-leg)
- Covered call (synthetic, 2-leg)
- Protective put (synthetic, 2-leg)

Key changes:
- Extended core.py to support 3+ leg strategies with proper column renaming
- Added quantity multipliers per leg for butterfly strategies (1:2:1 ratio)
- Added new rules for butterfly and iron condor strike ordering validation
- Updated definitions.py with correct column definitions for multi-leg strategies
- Added comprehensive test coverage with new multi-strike test fixture

https://claude.ai/code/session_01J51zgxv7jGDSscXN8sWEdX

* Remove unused reduce import from core.py

https://claude.ai/code/session_01J51zgxv7jGDSscXN8sWEdX

* Add calculated value assertions to new strategy tests

Updated tests to verify actual P&L calculations:
- Long call butterfly: entry=0.40, exit=0.05, pct=-0.88 (at 210/212.5/215)
- Long put butterfly: entry=0.40, exit=0.0, pct=-1.0 (puts expired worthless)
- Iron condor: entry=-1.90 (credit), exit=-0.025, pct=0.99 (kept premium)
- Iron butterfly: entry=-5.00 (credit), exit=-2.475, pct=0.50
- Covered call: entry=1.50, exit=2.45, pct=0.63
- Protective put: entry=8.40, exit=7.525, pct=-0.10

https://claude.ai/code/session_01J51zgxv7jGDSscXN8sWEdX

* Update README with new supported strategies

Added documentation for:
- Butterfly strategies (long/short call/put butterfly)
- Iron condor and reverse iron condor
- Iron butterfly and reverse iron butterfly
- Covered call and protective put (synthetic)

Also updated pip install version to 2.0.3.

https://claude.ai/code/session_01J51zgxv7jGDSscXN8sWEdX

* Address Copilot review comments

1. Fix lambda late binding in _apply_ratios (core.py)
   - Capture entry_col and exit_col as default arguments to avoid
     late binding issues in lambda functions

2. Add dte_range to triple/quadruple strike internal columns (definitions.py)
   - Restores dte_range field that was present in original code
   - Provides users with DTE range information in raw output

https://claude.ai/code/session_01J51zgxv7jGDSscXN8sWEdX

* Update tests/test_strategies.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update tests/test_strategies.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

README.md

@@ -12,9 +12,26 @@ Use cases for Optopsy:
 * Discover performance statistics on **percentage change** for various options strategies on a given stock
 
 ## Supported Option Strategies
-* Calls/Puts
-* Straddles/Strangles
-* Vertical Call/Put Spreads
+
+### Single Leg
+* Long/Short Calls
+* Long/Short Puts
+
+### Two Leg
+* Long/Short Straddles
+* Long/Short Strangles
+* Vertical Call Spreads (Bull/Bear)
+* Vertical Put Spreads (Bull/Bear)
+* Covered Call (synthetic)
+* Protective Put (synthetic)
+
+### Three Leg (Butterflies)
+* Long/Short Call Butterfly
+* Long/Short Put Butterfly
+
+### Four Leg
+* Iron Condor / Reverse Iron Condor
+* Iron Butterfly / Reverse Iron Butterfly
 
 ## Documentation
 Please see the [wiki](https://github.com/michaelchu/optopsy/wiki) for API reference.
@@ -29,7 +46,7 @@ You will need Python 3.8 or newer and Pandas 2.0.0 or newer and Numpy 1.26.0 or
 
 ### Installation
 ```
-pip install optopsy==2.0.2
+pip install optopsy==2.0.3
 ```
 
 ### Example

optopsy/__init__.py

@@ -13,6 +13,19 @@
     short_call_spread,
     long_put_spread,
     short_put_spread,
+    # Butterfly strategies
+    long_call_butterfly,
+    short_call_butterfly,
+    long_put_butterfly,
+    short_put_butterfly,
+    # Iron condor and iron butterfly strategies
+    iron_condor,
+    reverse_iron_condor,
+    iron_butterfly,
+    reverse_iron_butterfly,
+    # Covered strategies
+    covered_call,
+    protective_put,
 )
 from .datafeeds import csv_data
 
@@ -30,5 +43,18 @@
     "short_call_spread",
     "long_put_spread",
     "short_put_spread",
+    # Butterfly strategies
+    "long_call_butterfly",
+    "short_call_butterfly",
+    "long_put_butterfly",
+    "short_put_butterfly",
+    # Iron condor and iron butterfly strategies
+    "iron_condor",
+    "reverse_iron_condor",
+    "iron_butterfly",
+    "reverse_iron_butterfly",
+    # Covered strategies
+    "covered_call",
+    "protective_put",
     "csv_data",
 ]

optopsy/core.py

@@ -1,7 +1,6 @@
 from typing import Any, Callable, Dict, List, Optional, Tuple
 import pandas as pd
 import numpy as np
-from functools import reduce
 from .definitions import evaluated_cols
 from .checks import _run_checks
 
@@ -170,13 +169,25 @@ def _calculate_otm_pct(data: pd.DataFrame) -> pd.DataFrame:
     )
 
 
+def _get_leg_quantity(leg: Tuple) -> int:
+    """Get quantity for a leg, defaulting to 1 if not specified."""
+    return leg[2] if len(leg) > 2 else 1
+
+
 def _apply_ratios(data: pd.DataFrame, leg_def: List[Tuple]) -> pd.DataFrame:
-    """Apply position ratios (long/short multipliers) to entry and exit prices."""
+    """Apply position ratios (long/short multipliers) and quantities to entry and exit prices."""
     for idx in range(1, len(leg_def) + 1):
         entry_col = f"entry_leg{idx}"
         exit_col = f"exit_leg{idx}"
-        entry_kwargs = {entry_col: lambda r: r[entry_col] * leg_def[idx - 1][0].value}
-        exit_kwargs = {exit_col: lambda r: r[exit_col] * leg_def[idx - 1][0].value}
+        leg = leg_def[idx - 1]
+        multiplier = leg[0].value * _get_leg_quantity(leg)
+        # Use default arguments to capture values at each iteration (avoid late binding)
+        entry_kwargs = {
+            entry_col: lambda r, col=entry_col, m=multiplier: r[col] * m
+        }
+        exit_kwargs = {
+            exit_col: lambda r, col=exit_col, m=multiplier: r[col] * m
+        }
         data = data.assign(**entry_kwargs).assign(**exit_kwargs)
 
     return data
@@ -206,6 +217,16 @@ def _assign_profit(
     return data
 
 
+def _rename_leg_columns(
+    data: pd.DataFrame, leg_idx: int, join_on: List[str]
+) -> pd.DataFrame:
+    """Rename columns with leg suffix, excluding join columns."""
+    rename_map = {
+        col: f"{col}_leg{leg_idx}" for col in data.columns if col not in join_on
+    }
+    return data.rename(columns=rename_map)
+
+
 def _strategy_engine(
     data: pd.DataFrame,
     leg_def: List[Tuple],
@@ -237,19 +258,19 @@ def _rule_func(
     ) -> pd.DataFrame:
         return d if r is None else r(d, ld)
 
-    partials = [leg[1](data) for leg in leg_def]
+    # Pre-rename columns for each leg to avoid suffix issues with 3+ legs
+    partials = [
+        _rename_leg_columns(leg[1](data).copy(), idx, join_on or [])
+        for idx, leg in enumerate(leg_def, start=1)
+    ]
     suffixes = [f"_leg{idx}" for idx in range(1, len(leg_def) + 1)]
 
-    return (
-        reduce(
-            lambda left, right: pd.merge(
-                left, right, on=join_on, how="inner", suffixes=suffixes
-            ),
-            partials,
-        )
-        .pipe(_rule_func, rules, leg_def)
-        .pipe(_assign_profit, leg_def, suffixes)
-    )
+    # Merge all legs sequentially
+    result = partials[0]
+    for partial in partials[1:]:
+        result = pd.merge(result, partial, on=join_on, how="inner")
+
+    return result.pipe(_rule_func, rules, leg_def).pipe(_assign_profit, leg_def, suffixes)
 
 
 def _process_strategy(data: pd.DataFrame, **context: Any) -> pd.DataFrame:

optopsy/definitions.py

@@ -56,26 +56,24 @@
 
 triple_strike_internal_cols = [
     "underlying_symbol",
-    "underlying_price_entry",
+    "underlying_price_entry_leg1",
     "expiration",
     "dte_entry",
+    "dte_range",
     "option_type_leg1",
     "strike_leg1",
     "option_type_leg2",
     "strike_leg2",
     "option_type_leg3",
     "strike_leg3",
-    "entry",
-    "exit",
-    "long_profit",
-    "short_profit",
-    "long_pct_change",
-    "short_pct_change",
+    "total_entry_cost",
+    "total_exit_proceeds",
+    "pct_change",
 ]
 
 quadruple_strike_internal_cols = [
     "underlying_symbol",
-    "underlying_price_entry",
+    "underlying_price_entry_leg1",
     "expiration",
     "dte_entry",
     "dte_range",
@@ -87,12 +85,9 @@
     "strike_leg3",
     "option_type_leg4",
     "strike_leg4",
-    "entry",
-    "exit",
-    "long_profit",
-    "short_profit",
-    "long_pct_change",
-    "short_pct_change",
+    "total_entry_cost",
+    "total_exit_proceeds",
+    "pct_change",
 ]
 
 # base columns of dataframe after aggregation(minus the calculated columns)

optopsy/rules.py

@@ -26,3 +26,78 @@ def _rule_non_overlapping_strike(
     )
 
     return data.query(query)
+
+
+def _rule_butterfly_strikes(
+    data: pd.DataFrame, leg_def: List[Tuple]
+) -> pd.DataFrame:
+    """
+    Filter butterfly strategies to ensure proper strike ordering and equal width.
+
+    A butterfly requires:
+    - strike_leg1 < strike_leg2 < strike_leg3
+    - Equal wing widths: (strike_leg2 - strike_leg1) == (strike_leg3 - strike_leg2)
+
+    Args:
+        data: DataFrame containing butterfly strategy data
+        leg_def: List of tuples defining strategy legs
+
+    Returns:
+        Filtered DataFrame with valid butterfly strike configurations
+    """
+    if len(leg_def) != 3:
+        return data
+
+    return data.query(
+        "strike_leg1 < strike_leg2 < strike_leg3 & "
+        "(strike_leg2 - strike_leg1) == (strike_leg3 - strike_leg2)"
+    )
+
+
+def _rule_iron_condor_strikes(
+    data: pd.DataFrame, leg_def: List[Tuple]
+) -> pd.DataFrame:
+    """
+    Filter iron condor strategies to ensure proper strike ordering.
+
+    An iron condor requires 4 strikes in ascending order:
+    - strike_leg1 (long put) < strike_leg2 (short put) < strike_leg3 (short call) < strike_leg4 (long call)
+
+    Args:
+        data: DataFrame containing iron condor strategy data
+        leg_def: List of tuples defining strategy legs
+
+    Returns:
+        Filtered DataFrame with valid iron condor strike configurations
+    """
+    if len(leg_def) != 4:
+        return data
+
+    return data.query(
+        "strike_leg1 < strike_leg2 < strike_leg3 < strike_leg4"
+    )
+
+
+def _rule_iron_butterfly_strikes(
+    data: pd.DataFrame, leg_def: List[Tuple]
+) -> pd.DataFrame:
+    """
+    Filter iron butterfly strategies to ensure proper strike ordering.
+
+    An iron butterfly requires:
+    - strike_leg1 (long put) < strike_leg2 (short put) = strike_leg3 (short call) < strike_leg4 (long call)
+    - The short put and short call share the same strike (ATM)
+
+    Args:
+        data: DataFrame containing iron butterfly strategy data
+        leg_def: List of tuples defining strategy legs
+
+    Returns:
+        Filtered DataFrame with valid iron butterfly strike configurations
+    """
+    if len(leg_def) != 4:
+        return data
+
+    return data.query(
+        "strike_leg1 < strike_leg2 & strike_leg2 == strike_leg3 & strike_leg3 < strike_leg4"
+    )