OptionLab

https://rgaveiga.github.io/optionlab/
Admin
OptionLab is a Python library designed as a research tool for quickly evaluating options strategy...
Tokens:46,634
Snippets:202
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install OptionLab

Source: https://rgaveiga.github.io/optionlab

Install the library using pip.

```bash
pip install optionlab
```

--------------------------------

### Install OptionLab using pip

Source: https://rgaveiga.github.io/optionlab

Use this command to install the OptionLab library. Ensure pip is available in your environment.

```bash
pip install optionlab

```

--------------------------------

### Define Strategy Inputs as a Dictionary

Source: https://rgaveiga.github.io/optionlab

This example shows how to define input data for an options strategy using a Python dictionary. This format is accepted by the `run_strategy` function.

```python
input_data = {
    "stock_price": 164.04,
    "start_date": "2021-11-22",
    "target_date": "2021-12-17",
    "volatility": 0.272,
    "interest_rate": 0.0002,
    "min_stock": 120,
    "max_stock": 200,
    "strategy": [
        {
            "type": "call",
            "strike": 175.0,
            "premium": 1.15,
            "n": 100,
            "action":"sell"
        }
    ],
}

```

--------------------------------

### Define Strategy Inputs using Inputs Object

Source: https://rgaveiga.github.io/optionlab

This example demonstrates defining input data for an options strategy using the `optionlab.models.Inputs` object. This provides a more structured approach compared to a dictionary.

```python
from optionlab import Inputs

input_data = Inputs(
    stock_price = 164.04,
    start_date = "2021-11-22",
    target_date = "2021-12-17",
    volatility = 0.272,
    interest_rate = 0.0002,
    min_stock = 120,
    max_stock = 200,
    strategy = [
        {
            "type": "call",
            "strike": 175.0,
            "premium": 1.15,
            "n": 100,
            "action":"sell"
        }
    ],
)

```

--------------------------------

### GET /get_pl_profile_bs

Source: https://rgaveiga.github.io/optionlab/optionlab/support.html

Calculates the profit/loss profile and cost of an options trade on a target date before expiration using the Black-Scholes model.

```APIDOC
## GET /get_pl_profile_bs

### Description
Returns the profit/loss profile and cost of an options trade on a target date before expiration using the Black-Scholes model for option pricing.

### Parameters
#### Request Body
- **option_type** (string) - Required - Either 'call' or 'put'.
- **action** (string) - Required - Either 'buy' or 'sell'.
- **x** (float) - Required - Strike price.
- **val** (float) - Required - Initial option price.
- **r** (float) - Required - Annualized risk-free interest rate.
- **target_to_maturity_years** (float) - Required - Time remaining to maturity from the target date, in years.
- **volatility** (float) - Required - Annualized volatility of the underlying asset.
- **n** (int) - Required - Number of options.
- **s** (numpy.ndarray) - Required - Array of stock prices.
- **y** (float) - Optional - Annualized dividend yield.
- **commission** (float) - Optional - Brokerage commission.

### Response
#### Success Response (200)
- **profile** (float | numpy.ndarray) - Profit/loss profile.
- **cost** (float) - Cost of the option trade.
```

--------------------------------

### Get Profit/Loss Data

Source: https://rgaveiga.github.io/optionlab/optionlab/utils.html

Retrieves stock prices and their corresponding profit/loss profile for a specific leg or the entire strategy. Assumes 'outputs' contains valid calculation data.

```python
def get_pl(outputs: Outputs, leg: int | None = None) -> tuple[np.ndarray, np.ndarray]:
    """
    Returns the stock prices and the corresponding profit/loss profile of either
    a leg or the whole strategy.

    ### Parameters

    `outputs`: output data from a strategy calculation.

    `leg`: index of a strategy leg. The default is `None`, which means the whole
    strategy.

    ### Returns

    Array of stock prices and array or profits/losses.
    """

    if outputs.data.profit.size > 0 and leg and leg < outputs.data.profit.shape[0]:
        return outputs.data.stock_price_array, outputs.data.profit[leg]

    return outputs.data.stock_price_array, outputs.data.strategy_profit
```

--------------------------------

### Get Option Vega

Source: https://rgaveiga.github.io/optionlab/optionlab/black_scholes.html

Calculates the option's Greek Vega using provided parameters.

```APIDOC
## GET /option/vega

### Description
Calculates the option's Greek Vega.

### Method
GET

### Endpoint
/option/vega

### Parameters
#### Query Parameters
- **s0** (float) - Required - Spot price of the underlying asset.
- **years_to_maturity** (float) - Required - Time remaining to maturity, in years.
- **d1** (float | numpy.ndarray) - Required - d1 in Black-Scholes formula.
- **y** (float) - Optional - Annualized dividend yield. Defaults to 0.0.

### Response
#### Success Response (200)
- **vega** (float | numpy.ndarray) - Option's Greek Vega.

### Response Example
```json
{
  "vega": 0.12345
}
```
```

--------------------------------

### GET /get_pl_profile_stock

Source: https://rgaveiga.github.io/optionlab/optionlab/support.html

Calculates the profit/loss profile and cost of a stock position.

```APIDOC
## GET /get_pl_profile_stock

### Description
Returns the profit/loss profile and cost of a stock position.

### Parameters
#### Request Body
- **s0** (float) - Required - Initial stock price.
- **action** (string) - Required - Either 'buy' or 'sell'.
- **n** (int) - Required - Number of shares.
- **s** (numpy.ndarray) - Required - Array of stock prices.
- **commission** (float) - Optional - Brokerage commission.

### Response
#### Success Response (200)
- **profile** (numpy.ndarray) - Profit/loss profile.
- **cost** (float) - Cost of the stock position.
```

--------------------------------

### Initialize OptionLab Package Imports

Source: https://rgaveiga.github.io/optionlab

Imports core modules for strategy modeling, execution, plotting, and utility functions.

```python
from .models import Inputs
from .engine import run_strategy
from .plot import plot_pl
from .utils import get_pl, pl_to_csv

__docformat__ = "markdown"
__version__ = "1.5.1"
```

--------------------------------

### get_probability_of_touch

Source: https://rgaveiga.github.io/optionlab/optionlab/black_scholes.html

Calculates the probability that an option will ever get in-the-money (ITM) before expiration.

```APIDOC
## get_probability_of_touch

### Description
Calculates the probability that an option will ever get in-the-money (ITM) before expiration. This implementation follows equations 2.66 and 2.67 from 'The complete guide to option pricing formulas' by Espen Gaarder Haug.

### Parameters
- **option_type** (string) - Required - Either 'call' or 'put'.
- **s** (float) - Required - Current stock price.
- **x** (float | numpy.ndarray) - Required - Strike price(s).
- **r** (float) - Required - Annualized risk-free interest rate.
- **vol** (float) - Required - Annualized volatility.
- **years_to_maturity** (float) - Required - Time remaining to maturity in years.
- **y** (float) - Optional - Annualized dividend yield (default: 0.0).

### Returns
- **probability** (float | numpy.ndarray) - The probability that the option(s) will ever get in-the-money (ITM) before expiration.
```

--------------------------------

### Get d1 for Black-Scholes

Source: https://rgaveiga.github.io/optionlab/optionlab/black_scholes.html

Calculates the d1 value used in the Black-Scholes option pricing formula.

```APIDOC
## GET /option/d1

### Description
Calculates `d1` used in Black-Scholes formula.

### Method
GET

### Endpoint
/option/d1

### Parameters
#### Query Parameters
- **s0** (float | numpy.ndarray) - Required - Spot price(s) of the underlying asset.
- **x** (float | numpy.ndarray) - Required - Strike price(s).
- **r** (float) - Required - Annualized risk-free interest rate.
- **vol** (float | numpy.ndarray) - Required - Annualized volatility(ies).
- **years_to_maturity** (float) - Required - Time remaining to maturity, in years.
- **y** (float) - Optional - Annualized dividend yield. Defaults to 0.0.

### Response
#### Success Response (200)
- **d1** (float | numpy.ndarray) - `d1` in Black-Scholes formula.

### Response Example
```json
{
  "d1": 1.2345
}
```
```

--------------------------------

### Execute and Visualize Strategy

Source: https://rgaveiga.github.io/optionlab

Run the strategy evaluation and visualize the profit/loss profile.

```python
from optionlab import run_strategy, plot_pl

out = run_strategy(input_data)

print(out)

plot_pl(out)
```

--------------------------------

### Execute Strategy Calculation

Source: https://rgaveiga.github.io/optionlab/optionlab/engine.html

Main entry point for running a strategy calculation, accepting either an Inputs object or a dictionary.

```python
def run_strategy(inputs_data: Inputs | dict) -> Outputs:
    """
    Runs the calculation for a strategy.

    ### Parameters

    `inputs_data`: input data used in the strategy calculation.

    ### Returns

    Output data from the strategy calculation.
    """

    inputs = (
        inputs_data
        if isinstance(inputs_data, Inputs)
        else Inputs.model_validate(inputs_data)
    )

    data = _init_inputs(inputs)

    data = _run(data)

    return _generate_outputs(data)
```

--------------------------------

### Get Option Rho

Source: https://rgaveiga.github.io/optionlab/optionlab/black_scholes.html

Calculates the option's Greek Rho based on option type and Black-Scholes parameters.

```APIDOC
## GET /option/rho

### Description
Calculates the option's Greek Rho.

### Method
GET

### Endpoint
/option/rho

### Parameters
#### Query Parameters
- **option_type** (Literal['call', 'put']) - Required - Specifies whether the option is a 'call' or 'put'.
- **x** (float | numpy.ndarray) - Required - Strike price(s).
- **r** (float) - Required - Annualized risk-free interest rate.
- **years_to_maturity** (float) - Required - Time remaining to maturity, in years.
- **d2** (float | numpy.ndarray) - Required - d2 in Black-Scholes formula.

### Response
#### Success Response (200)
- **rho** (float | numpy.ndarray) - Option's Greek Rho.

### Response Example
```json
{
  "rho": 0.05678
}
```
```

--------------------------------

### Initialize and Process Strategy Data

Source: https://rgaveiga.github.io/optionlab/optionlab/engine.html

Handles the initialization of strategy metrics and updates profit calculations based on the model type.

```python
inputs = data.inputs

data.implied_volatility.append(0.0)
data.itm_probability.append(0.0)
data.probability_of_touch.append(0.0)
data.delta.append(0.0)
data.gamma.append(0.0)
data.vega.append(0.0)
data.rho.append(0.0)
data.theta.append(0.0)

data.cost[i] = data.previous_position[i]
data.profit[i] += data.previous_position[i]

if inputs.model == "array":
    data.profit_mc[i] += data.previous_position[i]

return data
```

--------------------------------

### Define Strategy Inputs via Dictionary

Source: https://rgaveiga.github.io/optionlab/optionlab.html

Configure strategy parameters using a standard Python dictionary.

```python
input_data = {
    "stock_price": 164.04,
    "start_date": "2021-11-22",
    "target_date": "2021-12-17",
    "volatility": 0.272,
    "interest_rate": 0.0002,
    "min_stock": 120,
    "max_stock": 200,
    "strategy": [
        {
            "type": "call",
            "strike": 175.0,
            "premium": 1.15,
            "n": 100,
            "action":"sell"
        }
    ],
}
```

--------------------------------

### Run Strategy and Plot Profit/Loss

Source: https://rgaveiga.github.io/optionlab

This code snippet shows how to execute an options strategy using `run_strategy` and visualize the profit/loss diagram with `plot_pl`. The `out` variable will contain the strategy's results.

```python
from optionlab import run_strategy, plot_pl

out = run_strategy(input_data)

print(out)

plot_pl(out)

```

--------------------------------

### Execute Options Strategy Calculation

Source: https://rgaveiga.github.io/optionlab/optionlab/engine.html

The run_strategy function serves as the primary entry point for processing strategy data and returning an Outputs object.

```python
  1"""
  2This module implements the `run_strategy` function.
  3
  4Given input data provided as either an `optionlab.models.Inputs` object or a dictionary,
  5`run_strategy` returns the results of an options strategy calculation (e.g., the
  6probability of profit on the target date) as an `optionlab.models.Outputs` object.
  7"""
  8
  9from __future__ import division
 10from __future__ import print_function
 11
 12import datetime as dt
 13
 14from numpy import zeros, array
 15
 16
 17from optionlab.black_scholes import get_bs_info, get_implied_vol
 18from optionlab.models import (
 19    Inputs,
 20    Action,
 21    Option,
 22    Stock,
 23    ClosedPosition,
 24    Outputs,
 25    BlackScholesModelInputs,
 26    ArrayInputs,
 27    OptionType,
 28    EngineData,
 29    PoPOutputs,
 30)
 31from optionlab.support import (
 32    get_pl_profile,
 33    get_pl_profile_stock,
 34    get_pl_profile_bs,
 35    create_price_seq,
 36    get_pop,
 37)
 38from optionlab.utils import get_nonbusiness_days
 39
 40
 41def run_strategy(inputs_data: Inputs | dict) -> Outputs:
 42    """
 43    Runs the calculation for a strategy.
 44
 45    ### Parameters
 46
 47    `inputs_data`: input data used in the strategy calculation.
 48
 49    ### Returns
 50
 51    Output data from the strategy calculation.
 52    """
 53
 54    inputs = (
 55        inputs_data
 56        if isinstance(inputs_data, Inputs)
 57        else Inputs.model_validate(inputs_data)
 58    )
 59
 60    data = _init_inputs(inputs)
 61
 62    data = _run(data)
 63
 64    return _generate_outputs(data)
 65
 66
 67def _init_inputs(inputs: Inputs) -> EngineData:
 68    data = EngineData(
 69        stock_price_array=create_price_seq(inputs.min_stock, inputs.max_stock),
 70        terminal_stock_prices=inputs.array if inputs.model == "array" else array([]),
 71        inputs=inputs,
 72    )
 73
 74    data.days_in_year = (
 75        inputs.business_days_in_year if inputs.discard_nonbusiness_days else 365
 76    )
 77
 78    if inputs.start_date and inputs.target_date:
 79        if inputs.discard_nonbusiness_days:
 80            n_discarded_days = get_nonbusiness_days(
 81                inputs.start_date, inputs.target_date, inputs.country
 82            )
 83        else:
 84            n_discarded_days = 0
 85
 86        data.days_to_target = (
 87            (inputs.target_date - inputs.start_date).days + 1 - n_discarded_days
 88        )
 89    else:
 90        data.days_to_target = inputs.days_to_target_date
 91
 92    for i, strategy in enumerate(inputs.strategy):
 93        data.type.append(strategy.type)
 94
 95        if isinstance(strategy, Option):
 96            data.strike.append(strategy.strike)
 97            data.premium.append(strategy.premium)
 98            data.n.append(strategy.n)
 99            data.action.append(strategy.action)
100            data.previous_position.append(strategy.prev_pos or 0.0)
101
102            if not strategy.expiration:
103                data.days_to_maturity.append(data.days_to_target)
104                data.use_bs.append(False)
105            elif isinstance(strategy.expiration, dt.date) and inputs.start_date:
106                if inputs.discard_nonbusiness_days:
107                    n_discarded_days = get_nonbusiness_days(
108                        inputs.start_date, strategy.expiration, inputs.country
109                    )
110                else:
111                    n_discarded_days = 0
112
113                data.days_to_maturity.append(
114                    (strategy.expiration - inputs.start_date).days
115                    + 1
116                    - n_discarded_days
117                )
118
119                data.use_bs.append(strategy.expiration != inputs.target_date)
120            elif isinstance(strategy.expiration, int):
121                if strategy.expiration >= data.days_to_target:
122                    data.days_to_maturity.append(strategy.expiration)
123
124                    data.use_bs.append(strategy.expiration != data.days_to_target)
125                else:
126                    raise ValueError(
127                        "Days remaining to maturity must be greater than or equal to the number of days remaining to the target date!"
128                    )
129            else:
130                raise ValueError("Expiration must be a date, an int or None.")
131
132        elif isinstance(strategy, Stock):
133            data.n.append(strategy.n)
134            data.action.append(strategy.action)
135            data.previous_position.append(strategy.prev_pos or 0.0)
136            data.strike.append(0.0)
```

--------------------------------

### Calculate Black-Scholes Option Information

Source: https://rgaveiga.github.io/optionlab/optionlab/black_scholes.html

Provides a comprehensive set of option metrics including prices and Greeks for both call and put options.

```python
def get_bs_info(
    s: float,
    x: FloatOrNdarray,
    r: float,
    vol: float,
    years_to_maturity: float,
    y: float = 0.0,
) -> BlackScholesInfo:
    """
    Provides information about call and put options calculated using the Black-Scholes
    formula.

    ### Parameters

    `s`: stock price.

    `x`: strike price(s).

    `r`: annualized risk-free interest rate.

    `vol`: annualized volatility.

    `years_to_maturity`: time remaining to maturity, in years.

    `y`: annualized dividend yield.

    ### Returns

    Information calculated using the Black-Scholes formula.
    """

    d1 = get_d1(s, x, r, vol, years_to_maturity, y)
    d2 = get_d2(s, x, r, vol, years_to_maturity, y)
    call_price = get_option_price("call", s, x, r, years_to_maturity, d1, d2, y)
    put_price = get_option_price("put", s, x, r, years_to_maturity, d1, d2, y)
    call_delta = get_delta("call", d1, years_to_maturity, y)
    put_delta = get_delta("put", d1, years_to_maturity, y)
    call_theta = get_theta("call", s, x, r, vol, years_to_maturity, d1, d2, y)
    put_theta = get_theta("put", s, x, r, vol, years_to_maturity, d1, d2, y)
    gamma = get_gamma(s, vol, years_to_maturity, d1, y)
    vega = get_vega(s, years_to_maturity, d1, y)
    call_rho = get_rho("call", x, r, years_to_maturity, d2)
    put_rho = get_rho("put", x, r, years_to_maturity, d2)
    call_itm_prob = get_itm_probability("call", d2, years_to_maturity, y)
    put_itm_prob = get_itm_probability("put", d2, years_to_maturity, y)
    call_prob_of_touch = get_probability_of_touch(
        "call", s, x, r, vol, years_to_maturity, y
    )
    put_prob_of_touch = get_probability_of_touch(
        "put", s, x, r, vol, years_to_maturity, y
    )

    return BlackScholesInfo(
        call_price=call_price,
        put_price=put_price,
        call_delta=call_delta,
        put_delta=put_delta,
        call_theta=call_theta,
        put_theta=put_theta,
        gamma=gamma,
        vega=vega,
        call_rho=call_rho,
        put_rho=put_rho,
        call_itm_prob=call_itm_prob,
        put_itm_prob=put_itm_prob,
        call_prob_of_touch=call_prob_of_touch,
        put_prob_of_touch=put_prob_of_touch,
    )
```

--------------------------------

### Validate Strategy Dates

Source: https://rgaveiga.github.io/optionlab/optionlab/models.html

Validates that all option expiration dates are on or after the target date, and that the start date is before the target date. Alternatively, it checks if days_to_target_date is provided and ensures no strategy expiration is mixed with it.

```python
expiration_dates = [
            strategy.expiration
            for strategy in self.strategy
            if isinstance(strategy, Option) and isinstance(strategy.expiration, dt.date)
        ]
        if self.start_date and self.target_date:
            if any(
                expiration_date < self.target_date
                for expiration_date in expiration_dates
            ):
                raise ValueError("Expiration dates must be after or on target date!")
            if self.start_date >= self.target_date:
                raise ValueError("Start date must be before target date!")
            return self
        if self.days_to_target_date:
            if len(expiration_dates) > 0:
                raise ValueError(
                    "You can't mix a strategy expiration with a days_to_target_date."
                )
            return self
        raise ValueError(
            "Either start_date and target_date or days_to_maturity must be provided"
        )
```

--------------------------------

### Define Strategy Inputs via Inputs Object

Source: https://rgaveiga.github.io/optionlab/optionlab.html

Configure strategy parameters using the library's built-in Inputs class.

```python
from optionlab import Inputs

input_data = Inputs(
    stock_price = 164.04,
    start_date = "2021-11-22",
    target_date = "2021-12-17",
    volatility = 0.272,
    interest_rate = 0.0002,
    min_stock = 120,
    max_stock = 200,
    strategy = [
        {
            "type": "call",
            "strike": 175.0,
            "premium": 1.15,
            "n": 100,
            "action":"sell"
        }
    ],
)
```

--------------------------------

### Calculate Probability of Option Expiring In-The-Money

Source: https://rgaveiga.github.io/optionlab/optionlab/black_scholes.html

Use this function to calculate the probability that an option will expire in-the-money (ITM). It requires parameters such as stock price, strike price, risk-free rate, volatility, and time to maturity. The function implements specific equations from 'The complete guide to option pricing formulas'.

```python
def get_probability_of_touch(
    option_type: OptionType,
    s: float,
    x: FloatOrNdarray,
    r: float,
    vol: float,
    years_to_maturity: float,
    y: float = 0.0,
) -> FloatOrNdarray:
    """
    Returns the probability(ies) that the option(s) will ever get in-the-money (ITM)
    before expiration.

    > [!NOTE]
    > This function implements equations 2.66 and 2.67 (see pages 80 and 81) in
    > *The complete guide to option pricing formulas*, 2nd edition, authored by
    > Espen Gaarder Haug, PhD, and published by McGraw-Hill.

    ### Parameters

    `option_type`: either *'call'* or *'put'*. 

    `s`: stock price.

    `x`: strike price(s).

    `r`: annualized risk-free interest rate.

    `vol`: annualized volatility.

    `years_to_maturity`: time remaining to maturity, in years.

    `y`: annualized dividend yield.

    ### Returns

    Probability(ies) that the option(s) will ever get in-the-money (ITM) before
    expiration.
    """

    mu = (r - y - 0.5 * vol * vol) / (vol * vol)
    lam = sqrt((mu * mu) + 2.0 * r / (vol * vol))
    sigma = vol * sqrt(years_to_maturity)
    z = log(x / s) / sigma + lam * sigma
    exp1 = mu + lam
    exp2 = mu - lam

    if option_type == "call":
        if s >= x:
            return 1.0
        else:
            return ((x / s) ** exp1) * stats.norm.cdf(-z) + (
                (x / s) ** exp2
            ) * stats.norm.cdf(2.0 * lam * sigma - z)
    elif option_type == "put":
        if s <= x:
            return 1.0
        else:
            return ((x / s) ** exp1) * stats.norm.cdf(z) + (
                (x / s) ** exp2
            ) * stats.norm.cdf(z - 2.0 * lam * sigma)
    else:
        raise ValueError("Option type must be either 'call' or 'put'!")
```

--------------------------------

### Black-Scholes Model Inputs

Source: https://rgaveiga.github.io/optionlab/optionlab/models.html

Defines input data for Black-Scholes model calculations. Includes interest rate and dividend yield.

```python
class BlackScholesModelInputs(TheoreticalModelInputs):
    """Defines the input data for the calculations using the Black-Scholes model."""

    model: Literal["black-scholes"] = "black-scholes"
    """It must be *'black-scholes'*."""

    interest_rate: float = Field(0.0, ge=0.0)
    """
    Annualized risk-free interest rate. 
    
    The default is 0.0.
    """

    dividend_yield: float = Field(0.0, ge=0.0, le=1.0)
    """
    Annualized dividend yield. 
    
    The default is 0.0.
    """

    __hash__ = object.__hash__
```

--------------------------------

### Laplace Distribution Inputs

Source: https://rgaveiga.github.io/optionlab/optionlab/models.html

Defines input data for calculations using a log-Laplace distribution of stock prices. Requires the 'laplace' model literal.

```python
class LaplaceInputs(TheoreticalModelInputs):
    """
    Defines the input data for the calculations using a log-Laplace distribution of
    stock prices.
    """

    model: Literal["laplace"] = "laplace"
    """It must be '*laplace*'."""

    mu: float
    """Annualized return of the underlying asset."""

    __hash__ = object.__hash__
```

--------------------------------

### run_strategy

Source: https://rgaveiga.github.io/optionlab/optionlab/engine.html

Executes the options strategy calculation based on input parameters.

```APIDOC
## FUNCTION run_strategy

### Description
Runs the calculation for an options strategy. It accepts either an `optionlab.models.Inputs` object or a dictionary, processes the strategy data, and returns an `optionlab.models.Outputs` object.

### Parameters
- **inputs_data** (Inputs | dict) - Required - Input data used in the strategy calculation.

### Returns
- **Outputs** - Output data from the strategy calculation.
```

--------------------------------

### Array Inputs for Strategy Returns

Source: https://rgaveiga.github.io/optionlab/optionlab/models.html

Defines input data for calculations using an array of strategy returns. Includes a validator for the array input.

```python
class ArrayInputs(BaseModel):
    """
    Defines the input data for the calculations when using an array of strategy
    returns.
    """

    model: Literal["array"] = "array"
    """It must be *'array*'."""

    array: np.ndarray
    """Array of strategy returns."""

    model_config = ConfigDict(arbitrary_types_allowed=True)

    @field_validator("array", mode="before")
    @classmethod
    def validate_arrays(cls, v: np.ndarray | list[float]) -> np.ndarray:
        """@private"""

        arr = np.asarray(v)
        if arr.shape[0] == 0:
            raise ValueError("The array is empty!")
        return arr
```

--------------------------------

### Generate Stock Price Sequence

Source: https://rgaveiga.github.io/optionlab/optionlab/support.html

Creates an array of stock prices from a minimum to a maximum value with $0.01 increments.

```python
if max_price > min_price:
    return round((arange((max_price - min_price) * 100 + 1) * 0.01 + min_price), 2)
else:
    raise ValueError("Maximum price cannot be less than minimum price!")
```

--------------------------------

### Retrieve Profit and Loss Data

Source: https://rgaveiga.github.io/optionlab/optionlab/utils.html

Returns stock prices and P/L profiles for a specific leg or the entire strategy. Requires output data from a strategy calculation.

```python
56def get_pl(outputs: Outputs, leg: int | None = None) -> tuple[np.ndarray, np.ndarray]:
57    """
58    Returns the stock prices and the corresponding profit/loss profile of either
59    a leg or the whole strategy.
60
61    ### Parameters
62
63    `outputs`: output data from a strategy calculation.
64
65    `leg`: index of a strategy leg. The default is `None`, which means the whole
66    strategy.
67
68    ### Returns
69
70    Array of stock prices and array or profits/losses.
71    """
72
73    if outputs.data.profit.size > 0 and leg and leg < outputs.data.profit.shape[0]:
74        return outputs.data.stock_price_array, outputs.data.profit[leg]
75
76    return outputs.data.stock_price_array, outputs.data.strategy_profit
```

--------------------------------

### Calculate Option Greeks and P/L Profile (Black-Scholes)

Source: https://rgaveiga.github.io/optionlab/optionlab/engine.html

Calculates option Greeks (delta, theta, rho) and profit/loss profiles using the Black-Scholes model. Handles call and put options, buy/sell actions, and considers previous positions. Use when Black-Scholes model is specified.

```python
float(
            get_implied_vol(
                type,
                data.premium[i],
                inputs.stock_price,
                data.strike[i],
                inputs.interest_rate,
                time_to_maturity,
                inputs.dividend_yield,
            )
        )
    )

    negative_multiplier = 1 if data.action[i] == "buy" else -1

    if type == "call":
        data.itm_probability.append(float(bs.call_itm_prob))
        data.probability_of_touch.append(float(bs.call_prob_of_touch))
        data.delta.append(float(bs.call_delta * negative_multiplier))
        data.theta.append(
            float(bs.call_theta / data.days_in_year * negative_multiplier)
        )
        data.rho.append(float(bs.call_rho * negative_multiplier))
    else:
        data.itm_probability.append(float(bs.put_itm_prob))
        data.probability_of_touch.append(float(bs.put_prob_of_touch))
        data.delta.append(float(bs.put_delta * negative_multiplier))
        data.theta.append(float(bs.put_theta / data.days_in_year * negative_multiplier))
        data.rho.append(float(bs.put_rho * negative_multiplier))

    if data.previous_position[i] > 0.0:  # Premium of the open position
        opt_value = data.previous_position[i]
    else:  # Current premium
        opt_value = data.premium[i]

    if data.use_bs[i]:
        target_to_maturity = (
            data.days_to_maturity[i] - data.days_to_target
        ) / data.days_in_year  # To consider the expiration date as a trading day

        data.profit[i], data.cost[i] = get_pl_profile_bs(
            type,
            action,
            data.strike[i],
            opt_value,
            inputs.interest_rate,
            target_to_maturity,
            inputs.volatility,
            data.n[i],
            data.stock_price_array,
            inputs.dividend_yield,
            inputs.opt_commission,
        )

        if inputs.model == "array":
            data.profit_mc[i] = get_pl_profile_bs(
                type,
                action,
                data.strike[i],
                opt_value,
                inputs.interest_rate,
                target_to_maturity,
                inputs.interest_rate,
                data.n[i],
                data.terminal_stock_prices,
                inputs.dividend_yield,
                inputs.opt_commission,
            )[0]
    else:
        data.profit[i], data.cost[i] = get_pl_profile(
            type,
            action,
            data.strike[i],
            opt_value,
            data.n[i],
            data.stock_price_array,
            inputs.opt_commission,
        )

        if inputs.model == "array":
            data.profit_mc[i] = get_pl_profile(
                type,
                action,
                data.strike[i],
                opt_value,
                data.n[i],
                data.terminal_stock_prices,
                inputs.opt_commission,
            )[0]

    return data
```

--------------------------------

### Export Profit and Loss to CSV

Source: https://rgaveiga.github.io/optionlab/optionlab/utils.html

Saves the stock prices and P/L profile to a CSV file. Defaults to 'pl.csv' if no filename is provided.

```python
 79def pl_to_csv(
 80    outputs: Outputs, filename: str = "pl.csv", leg: int | None = None
 81) -> None:
 82    """
 83    Saves the stock prices and corresponding profit/loss profile of either a leg
 84    or the whole strategy to a CSV file.
 85
 86    ### Parameters
 87
 88    `outputs`: output data from a strategy calculation.
 89
 90    `filename`: name of the CSV file.
 91
 92    `leg`: index of a strategy leg. The default is `None`, which means the whole
 93    strategy.
 94
 95    ### Returns
 96
 97    `None`.
 98    """
 99
100    if outputs.data.profit.size > 0 and leg and leg < outputs.data.profit.shape[0]:
101        arr = np.stack((outputs.data.stock_price_array, outputs.data.profit[leg]))
102    else:
103        arr = np.stack((outputs.data.stock_price_array, outputs.data.strategy_profit))
104
105    np.savetxt(
106        filename, arr.transpose(), delimiter=",", header="StockPrice,Profit/Loss"
107    )
```

--------------------------------

### Define Comprehensive Inputs for Strategy Calculation

Source: https://rgaveiga.github.io/optionlab/optionlab/models.html

Use the Inputs model for detailed strategy calculations, specifying parameters like stock price, volatility, interest rates, and strategy legs. Optional parameters for profit targets, loss limits, and commissions are also available.

```python
class Inputs(BaseModel):
    """Defines the input data for a strategy calculation."""

    stock_price: float = Field(gt=0.0)
    """Spot price of the underlying."""

    volatility: float = Field(ge=0.0)
    """Annualized volatility."""

    interest_rate: float = Field(ge=0.0)
    """Annualized risk-free interest rate."""

    min_stock: float = Field(ge=0.0)
    """Minimum value of the stock in the stock price domain."""

    max_stock: float = Field(ge=0.0)
    """Maximum value of the stock in the stock price domain."""

    strategy: list[StrategyLeg] = Field(..., min_length=1)
    """A list of strategy legs."""

    dividend_yield: float = Field(0.0, ge=0.0)
    """
    Annualized dividend yield. 
    
    The default is 0.0.
    """

    profit_target: Optional[float] = None
    """
    Target profit level. 
    
    The default is `None`, which means it is not calculated.
    """

    loss_limit: Optional[float] = None
    """
    Limit loss level. 
    
    The default is `None`, which means it is not calculated.
    """

    opt_commission: float = 0.0
    """
    Brokerage commission for options transactions. 
    
    The default is 0.0.
    """

    stock_commission: float = 0.0
    """
    Brokerage commission for stocks transactions. 
    
    The default is 0.0.
    """

    discard_nonbusiness_days: bool = True
    """
    Discards weekends and holidays when counting the number of days between
    two dates. 
    
    The default is `True`.
    """

    business_days_in_year: int = 252
    """
    Number of business days in a year. 
    
    The default is 252.
    """

    country: str = "US"
    """
    Country whose holidays will be counted if `discard_nonbusinessdays` is
    set to `True`. 
    
    The default is '*US*'.
    """

    start_date: dt.date | None = None
    """
    Start date in the calculations. 
    
    If not provided, `days_to_target_date` must be provided.
    """

    target_date: dt.date | None = None
    """
    Target date in the calculations. 
    
    If not provided, `start_date` and `target_date` must be provided.
    """

    days_to_target_date: int = Field(0, ge=0)
    """
    Days remaining to the target date. 
    
    If not provided, `start_date` and `target_date` must be provided.
    """

    model: TheoreticalModel = "black-scholes"
    """
    Theoretical model used in the calculations of probability of profit. 
    
    It can be *'black-scholes'* or *'array*'. 
    """

    array: np.ndarray = Field(default_factory=init_empty_array)
    """
    Array of terminal stock prices. 
    
    The default is an empty array.
    """

    model_config = ConfigDict(arbitrary_types_allowed=True)

    @field_validator("strategy")
    @classmethod
    def validate_strategy(cls, v: list[StrategyLeg]) -> list[StrategyLeg]:
        """@private"""

        
```

--------------------------------

### Create Price Sequence

Source: https://rgaveiga.github.io/optionlab/optionlab/support.html

Generates a sequence of stock prices between a minimum and maximum value. This function is cached for performance.

```python
@lru_cache
def create_price_seq(min_price: float, max_price: float) -> np.ndarray:
    """
    
```

--------------------------------

### Compute Expected Returns using Black-Scholes

Source: https://rgaveiga.github.io/optionlab/optionlab/support.html

Computes expected returns above and below a target value using the Black-Scholes model.

```python
def _compute_expected_returns_bs(
    s: np.ndarray,
    profit: np.ndarray,
    inputs: BlackScholesModelInputs,
    target: float = 0.01,
) -> tuple[float, float]:
    """
    Computes the expected returns above or below the target assuming the Black-Scholes
    model.

    ### Parameters

    `s`: array of stock prices.

    `profit`: array of profits and losses.

    `inputs`: input data used to estimate the probability of profit.

    `target`: target return.

    ### Returns

    Expected value above the target and expected value below the target.
    """

    expected_return_above_target: float
    expected_return_below_target: float

    mid_point = 0.5 * (profit[:-1] + profit[1:])
    weighted_profit = zeros(mid_point.shape[0])

    sigma = (
        inputs.volatility * sqrt(inputs.years_to_target_date)
        if inputs.volatility > 0.0
        else 1e-10
    )
    drift = (
        inputs.interest_rate
        - inputs.dividend_yield
        - 0.5 * inputs.volatility * inputs.volatility
    ) * inputs.years_to_target_date
    m = log(inputs.stock_price) + drift

    lval = np.where(s[:-1] > 0.0, log(s[:-1]), -np.inf)
    hval = log(s[1:])
    prob = np.clip(
        stats.norm.cdf((hval - m) / sigma) - stats.norm.cdf((lval - m) / sigma),
        0.0,
        1.0,
    )

    weighted_profit = mid_point * prob
    ind_above_target = np.where(mid_point >= target)
    ind_below_target = np.where(mid_point < target)
    sum_prob_above_target = prob[ind_above_target].sum()
    sum_prob_below_target = prob[ind_below_target].sum()
    tmp1 = weighted_profit[ind_above_target].sum()
    tmp2 = weighted_profit[ind_below_target].sum()

    expected_return_above_target = (
        round(tmp1 / sum_prob_above_target, 2) if sum_prob_above_target > 0.0 else 0.0
    )
    expected_return_below_target = (
        round(tmp2 / sum_prob_below_target, 2) if sum_prob_below_target > 0.0 else 0.0
    )

    return expected_return_above_target, expected_return_below_target
```

--------------------------------

### Define Black-Scholes Model Inputs

Source: https://rgaveiga.github.io/optionlab/optionlab/models.html

Defines the input data structure for Black-Scholes calculations with validation for interest rates and dividend yields.

```python
model: Literal["black-scholes"] = "black-scholes"
"""It must be *'black-scholes'*."""

interest_rate: float = Field(0.0, ge=0.0)
"""
Annualized risk-free interest rate. 

The default is 0.0.
"""

dividend_yield: float = Field(0.0, ge=0.0, le=1.0)
"""
Annualized dividend yield. 

The default is 0.0.
"""

__hash__ = object.__hash__
```

--------------------------------

### get_bs_info

Source: https://rgaveiga.github.io/optionlab/optionlab/black_scholes.html

Provides comprehensive information about call and put options based on the Black-Scholes formula.

```APIDOC
## get_bs_info

### Description
Provides information about call and put options calculated using the Black-Scholes formula.

### Parameters
- **s** (float) - stock price.
- **x** (FloatOrNdarray) - strike price(s).
- **r** (float) - annualized risk-free interest rate.
- **vol** (float) - annualized volatility.
- **years_to_maturity** (float) - time remaining to maturity, in years.
- **y** (float) - annualized dividend yield. Defaults to 0.0.

### Returns
- **BlackScholesInfo** - Information calculated using the Black-Scholes formula.
```

--------------------------------

### Generate Stock Price Sequence

Source: https://rgaveiga.github.io/optionlab/optionlab/support.html

Generates a sequence of stock prices from a minimum to a maximum price with an increment of $0.01. Ensure the maximum price is not less than the minimum price.

```python
179@lru_cache
180def create_price_seq(min_price: float, max_price: float) -> np.ndarray:
181    """
182    Generates a sequence of stock prices from a minimum to a maximum price with
183    increment $0.01.
184
185    ### Parameters
186
187    `min_price`: minimum stock price in the range.
188
189    `max_price`: maximum stock price in the range.
190
191    ### Returns
192
193    Array of sequential stock prices.
194    """
195
196    if max_price > min_price:
197        return round((arange((max_price - min_price) * 100 + 1) * 0.01 + min_price), 2)
198    else:
199        raise ValueError("Maximum price cannot be less than minimum price!")


```

--------------------------------

### Define Strategy Input Data

Source: https://rgaveiga.github.io/optionlab

Define strategy parameters using either a dictionary or an Inputs object.

```python
input_data = {
    "stock_price": 164.04,
    "start_date": "2021-11-22",
    "target_date": "2021-12-17",
    "volatility": 0.272,
    "interest_rate": 0.0002,
    "min_stock": 120,
    "max_stock": 200,
    "strategy": [
        {
            "type": "call",
            "strike": 175.0,
            "premium": 1.15,
            "n": 100,
            "action":"sell"
        }
    ],
}
```

```python
from optionlab import Inputs

input_data = Inputs(
    stock_price = 164.04,
    start_date = "2021-11-22",
    target_date = "2021-12-17",
    volatility = 0.272,
    interest_rate = 0.0002,
    min_stock = 120,
    max_stock = 200,
    strategy = [
        {
            "type": "call",
            "strike": 175.0,
            "premium": 1.15,
            "n": 100,
            "action":"sell"
        }
    ],
)
```

--------------------------------

### Initialize Empty Numpy Array

Source: https://rgaveiga.github.io/optionlab/optionlab/models.html

Helper function to return an empty numpy array. Marked as private.

```python
def init_empty_array() -> np.ndarray:
    """@private"""

    return np.array([])
```
Tokens:
Raw