optionlab

  1"""
  2## OptionLab is...
  3
  4... a Python library designed as a research tool for quickly evaluating options 
  5strategy ideas. It is intended for a wide range of users, from individuals learning 
  6about options trading to developers of quantitative strategies.
  7
  8**OptionLab** calculations can produce a number of useful outputs:
  9
 10- the profit/loss profile of the strategy on a user-defined target date
 11
 12- the range of stock prices for which the strategy is profitable
 13
 14- the Greeks associated with each leg of the strategy
 15
 16- the resulting debit or credit on the trading account
 17
 18- the maximum and minimum returns within a specified lower and higher price range 
 19of the underlying asset 
 20
 21- the expected profit and expected loss of the strategy
 22
 23- the probability of profit
 24
 25The probability of profit (PoP) of the strategy on the user-defined target date 
 26is calculated analytically by using the Black-Scholes model. Alternatively, 
 27the user can provide an array of terminal underlying asset prices obtained from 
 28other sources (e.g., the Heston model, a Laplace distribution, or a Machine 
 29Learning/Deep Learning model) to be used in the calculations instead of the 
 30Black-Scholes model. This allows **OptionLab** to function as a calculator that 
 31supports a variety of pricing models.
 32
 33An advanced feature of **OptionLab** that provides great flexibility in building 
 34complex dynamic strategies is the ability to include previously created positions 
 35as legs in a new strategy. Popular strategies that can benefit from this feature 
 36include the Wheel and Covered Call strategies.
 37
 38## OptionLab is not...
 39
 40... a platform for direct order execution. This capability has not been and 
 41probably will not be implemented.
 42
 43Backtesting and trade simulation using Monte Carlo have also not (yet) been 
 44implemented in the API.
 45
 46That being said, nothing prevents **OptionLab** from being integrated into an 
 47options quant trader's workflow alongside other tools.
 48
 49## Installation
 50
 51The easiest way to install **OptionLab** is using **pip**:
 52
 53```
 54pip install optionlab
 55```
 56
 57## Quickstart
 58
 59**OptionLab** is designed with ease of use in mind. An options strategy can be 
 60defined and evaluated with just a few lines of Python code. The API is streamlined, 
 61and the learning curve is minimal.
 62
 63The evaluation of a strategy is done by calling the `optionlab.engine.run_strategy` 
 64function provided by the library. This function receives the input data either 
 65as a dictionary or an `optionlab.models.Inputs` object.
 66
 67For example, let's say we wanted to calculate the probability of profit for naked 
 68calls on Apple stocks expiring on December 17, 2021. The strategy setup consisted 
 69of selling 100 175.00 strike calls for 1.15 each on November 22, 2021.
 70
 71The input data for this strategy can be provided in a dictionary as follows:
 72
 73```python
 74input_data = {
 75    "stock_price": 164.04,
 76    "start_date": "2021-11-22",
 77    "target_date": "2021-12-17",
 78    "volatility": 0.272,
 79    "interest_rate": 0.0002,
 80    "min_stock": 120,
 81    "max_stock": 200,
 82    "strategy": [
 83        {
 84            "type": "call",
 85            "strike": 175.0,
 86            "premium": 1.15,
 87            "n": 100,
 88            "action":"sell"
 89        }
 90    ],
 91}
 92```
 93
 94Alternatively, the input data could be defined as the `optionlab.models.Inputs` 
 95object below:
 96    
 97```python
 98from optionlab import Inputs
 99
100input_data = Inputs(
101    stock_price = 164.04,
102    start_date = "2021-11-22",
103    target_date = "2021-12-17",
104    volatility = 0.272,
105    interest_rate = 0.0002,
106    min_stock = 120,
107    max_stock = 200,
108    strategy = [
109        {
110            "type": "call",
111            "strike": 175.0,
112            "premium": 1.15,
113            "n": 100,
114            "action":"sell"
115        }
116    ],
117)
118```
119
120In both cases, the strategy itself is a list of dictionaries, where each dictionary
121defines a leg in the strategy. The fields in a leg, depending on the type of the
122leg, are described in `optionlab.models.Stock`, `optionlab.models.Option`, and
123`optionlab.models.ClosedPosition`.
124
125After defining the input data, we pass it to the `run_strategy` function as shown 
126below:
127
128```python
129from optionlab import run_strategy, plot_pl
130
131out = run_strategy(input_data)
132
133print(out)
134
135plot_pl(out)
136```
137
138The variable `out` is an `optionlab.models.Outputs` object that contains the 
139results from the calculations. By calling `print` with `out` as an argument, 
140these results are displayed on screen. 
141
142The `optionlab.plot.plot_pl` function, in turn, takes an `optionlab.models.Outputs` 
143object as its argument and plots the profit/loss diagram for the strategy.
144
145## Examples
146
147Examples for a number of popular options trading strategies can be found as 
148Jupyter notebooks in the [examples](https://github.com/rgaveiga/optionlab/tree/main/examples) 
149directory.
150"""
151
152from .models import Inputs
153from .engine import run_strategy
154from .plot import plot_pl
155from .utils import get_pl, pl_to_csv
156
157__docformat__ = "markdown"
158__version__ = "1.5.1"