bayesline.api.equity.PortfolioReturnsTieoutReportSettings#
- pydantic model bayesline.api.equity.PortfolioReturnsTieoutReportSettings#
Settings for a portfolio returns tie-out report.
Compares the engine’s computed daily portfolio returns against an uploaded reference return series, per hierarchy leaf. Aggregation across the hierarchy is unweighted (mean across leaves) — this is a tie-out sanity reading, not a P&L number. Metrics that only make sense NAV-weighted (
uploaded_return,cumulative_diff) are emitted as NaN at internal hierarchy nodes.Show JSON schema
{ "title": "PortfolioReturnsTieoutReportSettings", "description": "Settings for a portfolio returns tie-out report.\n\nCompares the engine's computed daily portfolio returns against an uploaded\nreference return series, per hierarchy leaf. Aggregation across the\nhierarchy is unweighted (mean across leaves) \u2014 this is a tie-out sanity\nreading, not a P&L number. Metrics that only make sense NAV-weighted\n(``uploaded_return``, ``cumulative_diff``) are emitted as NaN at internal\nhierarchy nodes.", "type": "object", "properties": { "report_type": { "const": "portfolio_returns_tieout", "default": "portfolio_returns_tieout", "description": "Report type discriminator", "title": "Report Type", "type": "string" }, "portfolio_hierarchy_settings": { "$ref": "#/$defs/PortfolioHierarchySettings" }, "leaf_reference_mapping": { "additionalProperties": { "$ref": "#/$defs/TieoutReferenceRef" }, "description": "Mapping from portfolio_id (a hierarchy leaf) to its uploaded reference series. Leaves without an entry contribute NaN to uploaded-side metrics and are excluded from coverage.", "title": "Leaf Reference Mapping", "type": "object" }, "hit_rate_buckets_bps": { "description": "Hit-rate threshold buckets, in basis points. For each bucket, the report computes the fraction of dates where |computed - uploaded| is within the threshold.", "items": { "exclusiveMinimum": 0, "type": "number" }, "title": "Hit Rate Buckets Bps", "type": "array" }, "calendar": { "$ref": "#/$defs/CalendarSettings" }, "returns_currency": { "default": "USD", "title": "Returns Currency", "type": "string" } }, "$defs": { "CalendarSettings": { "additionalProperties": false, "description": "Calendar settings carrying exchange filters to construct calendars from.", "properties": { "filters": { "default": [ [ "XNYS" ] ], "description": "The filters to apply. Each filter is a list of exchange MIC codes. The outer list will be treated as an OR conditions, while the inner lists will be treated as an AND conditions. For example, `[['A', 'B'], ['C']]` means that the holidays are the days where either A and B are both holidays, or C is a holiday.", "examples": [ [ [ "XNYS" ] ], [ [ "XNYS", "XNAS" ] ], [ [ "XNYS" ], [ "XNAS" ] ] ], "items": { "items": { "type": "string" }, "type": "array" }, "minItems": 1, "title": "Filters", "type": "array" } }, "title": "CalendarSettings", "type": "object" }, "PortfolioHierarchySettings": { "additionalProperties": false, "description": "Specifies portfolio hierarchies with arbitrary groupings (e.g. manager, etc.).", "properties": { "portfolio_schema": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "$ref": "#/$defs/PortfolioOrganizerSettings" } ], "description": "The portfolio organizer settings to use as an underlying schema of portfolios. The 'Default' schema is used by default.", "title": "Portfolio Schema" }, "groupings": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "title": "Groupings", "type": "object" }, "portfolio_ids": { "items": { "type": "string" }, "title": "Portfolio Ids", "type": "array" }, "benchmark_ids": { "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Benchmark Ids", "type": "array" }, "auto_decompose_levels": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "description": "When provided, each ``portfolio_id`` that is a FoF parent is automatically expanded at load time into one entry per descendant path (``parent:child:...:leaf``) plus a ``parent_path:{REST}`` entry at each non-leaf level capturing what wasn't decomposed there. Path-typed inputs (containing ``:``) are left unchanged for idempotence. Only ``len(auto_decompose_levels)`` is meaningful \u2014 it sets the maximum recursion depth; the cascade emits exactly that many system grouping columns named ``bayesline/level_N``, and the element values themselves are not consumed. Deeper branches stop expanding and are emitted as bare leaves (no ``:{REST}`` sibling is added below a truncated node for its own un-emitted children); NAV is still conserved because the lookthrough math at query time descends through the full subtree. So ``auto_decompose_levels=['fund', 'strategy']`` decomposes up to two levels and emits ``bayesline/level_1`` and ``bayesline/level_2`` columns in ``groupings`` carrying the parent ids at each level. Compatible with hand-rolled ``groupings``: the cascade merges them via path-walk inheritance under their bare names (see ``auto_decompose_hierarchy`` in ``portfolio_cascade``). ``None`` disables auto-decompose; an empty list is rejected. Capped at 100 to keep recursion well below Python's default limit; real FoF hierarchies rarely exceed a handful of levels.", "title": "Auto Decompose Levels" } }, "required": [ "portfolio_schema", "portfolio_ids", "benchmark_ids" ], "title": "PortfolioHierarchySettings", "type": "object" }, "PortfolioOrganizerSettings": { "additionalProperties": false, "description": "Definition of where to source portfolio data from.\n\nSpecifies which portfolios to enable (from different sources).\nDifferent sources (e.g. uploaded portfolios) can provide the same portfolio\nidentifiers. These settings allow to specify which portfolios to enable from\nwhich sources.", "properties": { "enabled_portfolios": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "type": "string" }, "type": "object" } ], "description": "The enabled portfolios from different sources. The key is the portfolio ID, and the value is the source (name of the underlying portfolio service). Pass a str to reference an entire portfolio source (e.g. all portfolios from an upload).", "title": "Enabled Portfolios" }, "auxiliary_portfolios": { "additionalProperties": { "type": "string" }, "description": "Portfolios pulled in by fund-of-funds (FoF) cascade. Informational: always recomputed from ``enabled_portfolios`` plus the FoF graph at load time. Persisted as-is on save; any stale values are overwritten on the next normalize. The loader's effective enabled set is the union of ``enabled_portfolios`` and ``auxiliary_portfolios`` with user-explicit entries winning on key collision.", "title": "Auxiliary Portfolios", "type": "object" } }, "required": [ "enabled_portfolios" ], "title": "PortfolioOrganizerSettings", "type": "object" }, "TieoutReferenceRef": { "additionalProperties": false, "description": "Reference to an uploaded reference time-series for one hierarchy leaf.", "properties": { "source": { "description": "Name of the uploaded time-series factors dataset that holds the reference series.", "title": "Source", "type": "string" }, "series": { "description": "Name of the series/column within the uploaded dataset.", "title": "Series", "type": "string" }, "kind": { "description": "How the series values should be interpreted. 'returns' are simple period returns; 'levels' are cumulative levels (e.g. NAV or index level).", "enum": [ "returns", "levels" ], "title": "Kind", "type": "string" } }, "required": [ "source", "series", "kind" ], "title": "TieoutReferenceRef", "type": "object" } }, "additionalProperties": false, "required": [ "portfolio_hierarchy_settings", "leaf_reference_mapping" ] }
- Config:
frozen: bool = True
extra: str = forbid
- Fields:
calendar (bayesline.api._src.equity.calendar_settings.CalendarSettings)hit_rate_buckets_bps (list[float])leaf_reference_mapping (dict[str, bayesline.api._src.equity.report.portfolio_returns_tieout.TieoutReferenceRef])portfolio_hierarchy_settings (bayesline.api._src.equity.portfoliohierarchy_settings.PortfolioHierarchySettings)report_type (Literal['portfolio_returns_tieout'])returns_currency (str)
- Validators:
-
field report_type:
Literal['portfolio_returns_tieout'] = 'portfolio_returns_tieout'# Report type discriminator
- Validated by:
_strip_unknown_on_load
-
field portfolio_hierarchy_settings:
PortfolioHierarchySettings[Required]# - Validated by:
_strip_unknown_on_load
-
field leaf_reference_mapping:
dict[str,TieoutReferenceRef] [Required]# Mapping from portfolio_id (a hierarchy leaf) to its uploaded reference series. Leaves without an entry contribute NaN to uploaded-side metrics and are excluded from coverage.
- Validated by:
_strip_unknown_on_load
-
field hit_rate_buckets_bps:
Annotated[list[Annotated[float]]] [Optional]# Hit-rate threshold buckets, in basis points. For each bucket, the report computes the fraction of dates where |computed - uploaded| is within the threshold.
- Constraints:
func = <function _require_unique at 0x7f6e989f09a0>
- Validated by:
_strip_unknown_on_load
-
field calendar:
CalendarSettings[Optional]# - Validated by:
_strip_unknown_on_load