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.

If you have access to the Option object when you subscribe to the Option universe or contract, you can set the assignment model immediately after you create the subscription.

// In Initialize
var option = AddOption("SPY");
option.SetOptionAssignmentModel(new DefaultOptionAssignmentModel());
# In Initialize
option = AddOption("SPY")
option.SetOptionAssignmentModel(DefaultOptionAssignmentModel())

Otherwise, set the assignment model in 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
        {
            option.SetOptionAssignmentModel(new DefaultOptionAssignmentModel());
        }    
    }
}
# In Initialize
self.SetSecurityInitializer(MySecurityInitializer(self.BrokerageModel, FuncSecuritySeeder(self.GetLastKnownPrices)))

# 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
            option.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.

public class MyOptionAssignmentModel : IOptionAssignmentModel 
{
    public OptionAssignmentResult GetAssignment(OptionAssignmentParameters parameters)
    {
        var option = parameters.Option;
        if (IsInTheMoney(option))
        {
            return new OptionAssignmentResult(option.Holdings.AbsoluteQuantity, "tag");
        }
        return OptionAssignmentResult.Null;
    }
}
class MyOptionAssignmentModel:

    def GetAssignment(self, parameters: OptionAssignmentParameters) -> OptionAssignmentResult:
        option = parameters.Option
        if self.IsInTheMoney(option):
            return OptionAssignmentResult(option.Holdings.AbsoluteQuantity, "tag")
        return OptionAssignmentResult.Null

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 Option assignments, set the Option assignment model to the NullOptionAssignmentModel.

option.SetOptionAssignmentModel(new NullOptionAssignmentModel());
option.SetOptionAssignmentModel(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: