Options Models

Assignment

Introduction

If you sell an Option in a backtest, an assignment model can simulate an Option exercise order on behalf of the buyer and assign you to complete the requirements of the contract.

Set Models

To set the assignment model of an Option, call the SetOptionAssignmentModel method of the Option object inside a security initializer.

// In Initialize
SetSecurityInitializer(new MySecurityInitializer(BrokerageModel, new FuncSecuritySeeder(GetLastKnownPrices)));

// Outside of the algorithm class
class MySecurityInitializer : BrokerageModelSecurityInitializer
{
    public MySecurityInitializer(IBrokerageModel brokerageModel, ISecuritySeeder securitySeeder)
        : base(brokerageModel, securitySeeder) {}    
    
    public override void Initialize(Security security)
    {
        // First, call the superclass definition
        // This method sets the reality models of each security using the default reality models of the brokerage model
        base.Initialize(security);

        // Next, overwrite the assignment model        
        if (security.Type == SecurityType.Option) // Option type
        {
            (security as Option).SetOptionAssignmentModel(new DefaultOptionAssignmentModel());
        }    
    }
}
# In Initialize
self.set_security_initializer(MySecurityInitializer(self.brokerage_model, FuncSecuritySeeder(self.get_last_known_prices)))

# Outside of the algorithm class
class MySecurityInitializer(BrokerageModelSecurityInitializer):

    def __init__(self, brokerage_model: IBrokerageModel, security_seeder: ISecuritySeeder) -> None:
        super().__init__(brokerage_model, security_seeder)
    def initialize(self, security: Security) -> None:
        # First, call the superclass definition
        # This method sets the reality models of each security using the default reality models of the brokerage model
        super().initialize(security)

        # Next, overwrite the assignment model        
        if security.Type == SecurityType.Option: # Option type
            security.SetOptionAssignmentModel(DefaultOptionAssignmentModel())

Default Behavior

The default Option assignment model is the DefaultOptionAssignmentModel. The DefaultOptionAssignmentModel scans your portfolio every hour. It considers exercising American-style Options if they are within 4 days of their expiration and it considers exercising European-style Options on their day of expiration. If you have sold an Option that's 5% in-the-money and the Option exercise order is profitable after the cost of fees, this model exercises the Option.

To view the implementation of this model, see the LEAN GitHub repository.

Model Structure

Option assignment models should implement the IOptionAssignmentModel interface. Extensions of the IOptionAssignmentModel interface must implement the GetAssignment method, which automatically fires at the top of each hour and returns the Option assignments to generate.

Option assignment models should extend the NullOptionAssignmentModel class. Extensions of the NullOptionAssignmentModel class must implement the GetAssignment method, which automatically fires at the top of each hour and returns the Option assignments to generate.

// In the security initializer, set the custom Option assignment model
(security as Option).SetOptionAssignmentModel(new MyOptionAssignmentModel());

// Define the custom Option assignment model outside of the algorithm
public class MyOptionAssignmentModel : IOptionAssignmentModel
{
    public OptionAssignmentResult GetAssignment(OptionAssignmentParameters parameters)
    {
        var option = parameters.Option;
        // Check if the contract is ITM
        if ((option.Right == OptionRight.Call && option.Underlying.Price > option.StrikePrice) ||
            (option.Right == OptionRight.Put && option.Underlying.Price < option.StrikePrice))
        {
            return new OptionAssignmentResult(option.Holdings.AbsoluteQuantity, "MyTag");
        }
        return OptionAssignmentResult.Null;
    }
}
# In the security initializer, set the custom Option assignment model
security.SetOptionAssignmentModel(MyOptionAssignmentModel())

# Define the custom Option assignment model outside of the algorithm
class MyOptionAssignmentModel(NullOptionAssignmentModel):

    def GetAssignment(self, parameters: OptionAssignmentParameters) -> OptionAssignmentResult:
        option = parameters.Option
        # Check if the contract is ITM
        if option.Right == OptionRight.Call and option.Underlying.Price > option.StrikePrice \
            or option.Right == OptionRight.Put and option.Underlying.Price < option.StrikePrice:
            return OptionAssignmentResult(option.Holdings.AbsoluteQuantity, "MyTag")
        return OptionAssignmentResult.Null

For a full example algorithm, see this backtestthis backtest.

The OptionAssignmentParameters object has the following members:

To exercise the Option, return an OptionAssignmentResult with a positive quantity. Otherwise, return OptionAssignmentResult.Null. The OptionAssignmentResult constructor accepts the following arguments:

ArgumentData TypeDescriptionDefault Value
quantitydecimalfloatThe quantity to assign
tagstringstrThe order tag to use

Disable Assignments

To disable early Option assignments, set the Option assignment model to the NullOptionAssignmentModel.

(security as Option).SetOptionAssignmentModel(new NullOptionAssignmentModel());
security.set_option_assignment_model(NullOptionAssignmentModel())

Examples

Demonstration Algorithms
CustomOptionAssignmentRegressionAlgorithm.py Python CustomOptionAssignmentRegressionAlgorithm.cs C#

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: