Configurable Rolling Date With DataMappingMode

[AlexCatarino]

Expected Behavior

We can configure the behavior of DataMappingMode.LastTradingDate to roll the contract x days before. Also, restrict the contracts to the selected few. For example, Gold listed months include Feb, Apr, Jun, Aug, Oct, Dec, but Oct historically has weak open interest. Most systematic traders only hold Feb, Apr, Jun, Aug, Dec.

Actual Behavior

We are locked to the LastTradingDate, and most brokers, such as Interactive Brokers or TradeStation, will force liquidate physically settled futures many days prior to expiry during live trading.

Potential Solution

N/A

Checklist

• I have completely filled out this template
• I have confirmed that this issue exists on the current master branch
• I have confirmed that this is not a duplicate issue by searching issues

[brandon-68]

Adding context and a worked example for the engineering team's consideration

Below is an illustrative usage example showing how the two proposed additions would compose. The exact API is for the engineering team to design — this is provided as a worked specification of the user-facing behaviour.

self.add_future( Futures.Metals.MICRO_GOLD, data_mapping_mode=DataMappingMode.TRADING_DAYS_BEFORE_EXPIRY, roll_offset_trading_days=30, held_contract_months=[2, 4, 6, 8, 12] # skip Oct (weak liquidity) )

Two related additions, intended to compose:

1. DataMappingMode.TRADING_DAYS_BEFORE_EXPIRY (new mapping mode)
Rolls the mapped contract N trading days before the current contract's expiry date. N is configured via a new roll_offset_trading_days: int parameter on add_future.

This is intended as an additive new mode rather than a modification of DataMappingMode.LastTradingDate, to preserve backward compatibility.

Worked example: MGC April 2026 contract, expiry date 28 April 2026, roll_offset_trading_days=30. The mapped contract rolls on approximately 16 March 2026 (30 trading days before 28 April, accounting for the 3 April Good Friday holiday). Before that date, the mapped contract is the April 2026 contract. From that date onward, it's the next eligible contract (June 2026 under the standard MGC cycle). The user-configurable offset lets each instrument carry a different roll buffer calibrated against its broker's force-liquidation timing plus a safety margin.

2. held_contract_months (new parameter on add_future)
Optional int[] of expiry month numbers (1–12). Restricts which expiry months are eligible to be rolled into. Consistent with the existing FutureFilterUniverse.ExpirationCycle(int[] months) API.

If omitted, behaviour defaults to the product's full listed cycle (i.e. unchanged from today).

Combined behaviour (both features used together)
Combined semantics: "Roll N trading days before the current contract's expiry date, into the nearest contract whose expiry month is in held_contract_months and which has a later expiry than the current one."

Worked example for monthly-listed instruments: With held_contract_months=[2, 4, 6, 8, 12] and data_mapping_mode=DataMappingMode.TRADING_DAYS_BEFORE_EXPIRY on BTC futures (which list every calendar month), the mapped contract rolls 5 times per year rather than 12 — since rolls are triggered only when held-cycle contracts approach their own expiry, and only the 5 held-cycle months produce roll events.

Interaction with contract_depth_offset
held_contract_months should compose with contract_depth_offset such that the depth offset walks forward through the held cycle, not the full listed cycle. For example, with held_contract_months=[2, 4, 6, 8, 12] and contract_depth_offset=1, when the front held month is April the back month resolves to June (the next held month), not May. Otherwise the held-month filter would leak — a user who has explicitly excluded Oct shouldn't end up with an Oct contract via the depth-offset path.

If held_contract_months is omitted, contract_depth_offset behaviour is unchanged (walks the listed cycle).

Motivation
The current four mapping modes (OpenInterest, OpenInterestAnnual, LastTradingDay, FirstDayMonth) are sufficient for backtests and for live trading on financially-settled contracts, but produce roll dates that are too late for live trading on physically-settled futures via brokers like Interactive Brokers or TradeStation, which force-liquidate physical contracts well before expiry date.

The current workaround (manually liquidating and reopening on a scheduled basis outside LEAN's continuous-contract machinery) breaks the synchronisation between the back-adjusted continuous price series used for signal generation and the actual broker-held contract, which can produce material PnL differences in commodity futures.

A related discussion from 2017: First Notice vs Expiry on futures.
The held_contract_months extension is independently useful even with existing mapping modes — products like gold (weak Oct liquidity) and lean hogs (weak May liquidity) have listed contract months that are unsuitable for holding regardless of when the roll fires.

Happy to clarify any aspect of this proposal further. The intent is to provide concrete user-facing semantics; the engineering team is best positioned to determine the cleanest internal architecture and parameter naming.

[eeyore82]

This change will really help those who use continuous futures for signal generation in live trade

[cchews]

As a user of CSI Futures Data, i have wondered why the roll options suggested here have been sorely missing from QC all these while. Definitely a must have to implement these recommendations in QC, especially for futures traders.

[sht0000-Ger]

Very good suggestions here. Can we have the fix implemented?

[16DouglasTimothy]

Very good suggestion

[ysy-01]

Great teamwork by QC on keeping the futures trading feature running smoothly. This new suggestion will make live trading a lot more practical.