bayesline.api.equity.HoldingsOverrideWindow

pydantic model bayesline.api.equity.HoldingsOverrideWindow

A time-windowed set of holdings overrides for a single portfolio.

Each override is re-applied at every rebalance tick of the window (see PortfolioOverride.rebalance_frequency; the window’s start date is always a tick) and the resulting share count is held between ticks.

Targets with no price. An override can only be turned into a position on a date where the target has a price in the risk dataset. On any other date (not yet listed, delisted, id not valid yet, off-dataset) the target is held at zero — and any baseline holding of it is treated as zero, so it is not held either. The override then takes effect at the first rebalance tick on which the target is priced. Nothing is held in its place: the portfolio is simply smaller by that amount until then (cash is not modelled), so normalized weights and returns are those of the positions that could be held. Consequences:

• With rebalance_frequency=NEVER the only tick is the window start; an override on a target unpriced there never takes effect in the window.

• An override of 0 on a target keeps it out of the book for the whole window, priced or not.

• Overrides never fail for lack of a price; there is no error to catch.

Show JSON schema

{
   "title": "HoldingsOverrideWindow",
   "description": "A time-windowed set of holdings overrides for a single portfolio.\n\nEach override is re-applied at every rebalance tick of the window (see\n``PortfolioOverride.rebalance_frequency``; the window's start date is always\na tick) and the resulting share count is held between ticks.\n\n**Targets with no price.** An override can only be turned into a position on\na date where the target has a price in the risk dataset. On any other date\n(not yet listed, delisted, id not valid yet, off-dataset) the target is held\nat zero \u2014 and any baseline holding of it is treated as zero, so it is not\nheld either. The override then takes effect at the first rebalance tick on\nwhich the target is priced. Nothing is held in its place: the portfolio is\nsimply smaller by that amount until then (cash is not modelled), so\nnormalized weights and returns are those of the positions that could be\nheld. Consequences:\n\n- With ``rebalance_frequency=NEVER`` the only tick is the window start; an\n  override on a target unpriced there never takes effect in the window.\n- An override of ``0`` on a target keeps it out of the book for the whole\n  window, priced or not.\n- Overrides never fail for lack of a price; there is no error to catch.",
   "type": "object",
   "properties": {
      "snapshot_date": {
         "anyOf": [
            {
               "format": "date",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "If set, replace the portfolio's holdings within this window with the full holdings as of this date. Overrides are then applied on top. If None, only the explicit overrides are applied.",
         "title": "Snapshot Date"
      },
      "start_date": {
         "description": "Override effective start date.",
         "format": "date",
         "title": "Start Date",
         "type": "string"
      },
      "end_date": {
         "description": "Override effective end date.",
         "format": "date",
         "title": "End Date",
         "type": "string"
      },
      "overrides": {
         "additionalProperties": {
            "type": "number"
         },
         "description": "Mapping of target_id (a leaf asset_id or a child portfolio_id) to an override value, applied after snapshot replacement. Each value is interpreted per ``override_unit``. A leaf target with no price on a date is held at zero on that date and picks up the override at the first priced rebalance tick (see the class docstring).",
         "title": "Overrides",
         "type": "object"
      },
      "override_unit": {
         "$ref": "#/$defs/OverrideUnit",
         "default": "nav",
         "description": "How to interpret the ``overrides`` values. NAV (default): an absolute target NAV in the report currency. WEIGHT: a target fraction of the parent portfolio's own total NAV, supported only for child-portfolio targets and for leaf targets on fund-of-fund / source portfolios (a weight on a post-lookthrough / non-cascade leaf target is rejected)."
      }
   },
   "$defs": {
      "OverrideUnit": {
         "description": "Interpretation of the float values in ``HoldingsOverrideWindow.overrides``.",
         "enum": [
            "nav",
            "weight"
         ],
         "title": "OverrideUnit",
         "type": "string"
      }
   },
   "required": [
      "start_date",
      "end_date"
   ]
}

Config:

• frozen: bool = True

Fields:

• end_date (datetime.date)

• override_unit (bayesline.api._src.equity.report.scenarios.OverrideUnit)

• overrides (dict[str, float])

• snapshot_date (datetime.date | None)

• start_date (datetime.date)

field snapshot_date: date | None = None

If set, replace the portfolio’s holdings within this window with the full holdings as of this date. Overrides are then applied on top. If None, only the explicit overrides are applied.

field start_date: date [Required]

Override effective start date.

field end_date: date [Required]

Override effective end date.

field overrides: dict[str, float] [Optional]

Mapping of target_id (a leaf asset_id or a child portfolio_id) to an override value, applied after snapshot replacement. Each value is interpreted per override_unit. A leaf target with no price on a date is held at zero on that date and picks up the override at the first priced rebalance tick (see the class docstring).

field override_unit: OverrideUnit = OverrideUnit.NAV

How to interpret the overrides values. NAV (default): an absolute target NAV in the report currency. WEIGHT: a target fraction of the parent portfolio’s own total NAV, supported only for child-portfolio targets and for leaf targets on fund-of-fund / source portfolios (a weight on a post-lookthrough / non-cascade leaf target is rejected).