📡 Signals and Exposure in TOM

The signals section of a TOM object defines when your strategy enters or exits trades — effectively overriding any date or period-based scheduling from leg definitions.

Signals enable you to control the exact timing of entries and exits using custom dates or exposure levels, allowing for precise alignment with external models, indicators, or event data.

🧭 When to Use Signals

By default, TOM strategies open and roll positions based on the min_dte rule (if enabled).
However, when you send to the engine explicit entry and/or exit instructions inside a signals or exposure section.

This lets you:

• Run backtests aligned with your own buy/sell model outputs

• Synchronize option positions with market timing or macro signals

• Test the impact of discrete exposure changes (long/flat periods, rotations, etc.)

⚙️ Signal Input Types

TOM supports two main ways to define trade timing:

1. Explicit signal dates – Lists of entry and exit timestamps

2. Exposure timeline – A continuous series of exposure values that TOM converts into signals automatically

Both methods achieve the same goal: defining when structures open or close.
The right choice depends on your data source and use case.

1️⃣ Explicit Entry/Exit Signals

Use the signals object to define entry and exit events directly.

Example

"signals": {
  "entries": [
    "2018-01-31", "2018-03-31", "2018-05-31",
    "2018-07-31", "2018-09-30", "2018-11-30"
  ],
  "exits": [
    "2018-02-28", "2018-04-30", "2018-06-30",
    "2018-08-31", "2018-10-31", "2018-12-31"
  ]
}

Behavior

• On each date in entries, TOM opens a new structure following the leg definitions.

• On each date in exits, TOM closes all active structures.

• Dates must fall within the global from_date–to_date range.

• Entries and exits can overlap or repeat — TOM handles multiple open/close cycles automatically.

Notes

• Dates are in YYYY-MM-DD format.

• Non-trading days are automatically adjusted to the nearest valid session.

• If an entry date occurs while a position is still open, TOM will open a new one.

• If min_dte is enabled, TOM will continue to roll positions from every entry date to the closest exit date. 

2️⃣ Exposure Timeline

Instead of manually listing entry and exit dates, you can provide an exposure timeline — a sequence of exposure values over time.
The TOM engine then generates signals automatically whenever exposure changes.

Example

"exposure": [
  {"datetime": "2018-01-23", "exposure": 1},
  {"datetime": "2018-02-02", "exposure": 2},
  {"datetime": "2018-02-14", "exposure": 3},
  {"datetime": "2018-02-20", "exposure": 2}
]

How It Works

• exposure represents relative position intensity — often corresponding to signal strength, risk level, or allocation size.

• When exposure increases, TOM generates entry signals for the added exposure.

• When exposure decreases, TOM generates exit signals for the reduced portion.

• A change from 0 → 1 opens a new structure; 1 → 0 closes all positions.

• Exposure can be integer or fractional (e.g., 1.5 = partial exposure).

• If min_dte rolls are enabled, TOM will generate rolls even for the periods where exposure is unchanged. 

This format is ideal when you already have a daily signal series or output from a model (e.g., “market exposure over time”).

🧩 Comparison: Signals vs Exposure

✅ Requirements & Validation

• Either signals or exposure may be used — not both.
• Entry/exit dates must lie within from_date–to_date.
• Exposure values must be numeric (int or float).
• When both signals and exposure parameters are missing, TOM will try to enter trades at the end of every year and roll it to the end of the following year. 

🧾 Example: Full TOM with Signals

{
  "strategy_id": "Signal-Based Short Put",
  "signals": {
    "entries": ["2018-01-31", "2018-03-31", "2018-05-31"],
    "exits": ["2018-02-28", "2018-04-30", "2018-06-30"]
  },
  "initial_equity": 100000,
  "equity_type": "compounding",
  "from_date": "2018-01-01",
  "to_date": "2025-01-01",
  "option_expiry_type": "Standard",
  "legs": [
    {
      "id": "Short Put",
      "underlying_id": "IND.ES",
      "options_family_id": "IND.ES",
      "type": "p",
      "weight_type": "notional",
      "weight": -1,
      "expiry_dte_min": 30,
      "expiry_nearest": "1",
      "strike_type": "delta",
      "strike_value": 0.25,
      "period": "month",
      "period_contract": "All"
    }
  ]
}

🧾 Example: Full TOM with Exposure Timeline

{
  "strategy_id": "Exposure-Based Short Put",
  "exposure": [
    {"datetime": "2018-01-23", "exposure": 1},
    {"datetime": "2018-02-02", "exposure": 2},
    {"datetime": "2018-02-14", "exposure": 3},
    {"datetime": "2018-02-20", "exposure": 2}
  ],
  "initial_equity": 100000,
  "equity_type": "compounding",
  "from_date": "2018-01-01",
  "to_date": "2025-01-01",
  "option_expiry_type": "Standard + Serial",
  "legs": [
    {
      "id": "Short Put",
      "underlying_id": "IND.ES",
      "options_family_id": "IND.ES",
      "type": "p",
      "weight_type": "notional",
      "weight": -1,
      "expiry_dte_min": 30,
      "expiry_nearest": "1",
      "strike_type": "delta",
      "strike_value": 0.25,
      "period": "month",
      "period_contract": "All"
    }
  ]
}