bayesline.api.equity.XSRReportSettings#

model XSRReportSettings#

Settings for an XSR (cross-sectional risk) report.

Every cell is a (date, portfolio, factor-or-idiosyncratic row, asset) group, and its metric columns are the seven risk observables — Exposure, Volatility, Correlation, Contribution, Beta, RelativeExposure and RelativeContribution — followed by two the positions under them give:

ExposureRaw
the loading per unit of the cell’s own position: an asset’s own loading on a single-asset row, and the holdings-normalized basket of the group’s assets on a grouped one. A group holding nothing shows the equal-weight basket of the assets it names, and a group whose holdings cancel to no net position shows nothing — there is no basket to normalize.

Weight or PositionValue
the cell’s own position, named for the unit the report carries positions in: with normalize_holdings it is the cell’s signed share of the NAV of the book it is measured against and is called Weight; without it it is the position value in the report currency and is called PositionValue. Read metric_cols for the name in force.

so that Exposure = Weight * ExposureRaw, or Exposure = PositionValue * ExposureRaw, wherever the raw quantity is defined — one identity, in whichever unit the report is carrying. A loading belongs to one driver, so ExposureRaw and Exposure are null on a row naming more than one driver — a factor group or the whole book — in every analytics space: exposures to different factors are not commensurable and do not add. The position column describes a position rather than an exposure and reads the same on every row.

Three distinct quantities carry the one Volatility label, and which one a row shows follows from the row rather than from a setting:

a single-factor row shows that factor’s own volatility, and the idiosyncratic row of a single-asset cell that asset’s own specific volatility — both properties of the model, independent of the holdings;

the idiosyncratic row of a multi-asset cell shows the volatility of the normalized basket ExposureRaw describes, which is the same ladder: the equal-weight basket where nothing is held, and nothing where the holdings cancel;

a factor-group row shows the volatility of the portfolio’s own holdings over that group’s factors, not of the asset cell.

Fields#
Field	Type	Required	Default
`analytics_space`	`Literal`[‘absolute’, ‘active’, ‘benchmark’]	No	`'absolute'`
`annualize`	`bool`	No	`True`
`backfill_holdings`	`bool`	No	`False`
`calendar`	`CalendarSettings`	No	factory
`currency`	`str` \| `None`	No	`None`
`factor_cov_settings`	`FactorCovarianceSettings`	No	factory
`factor_model_settings`	`str` \| `int` \| `FactorRiskModelSettings`	Yes
`idio_vol_settings`	`IdioVolSettings`	No	factory
`name_contribution_basis`	`Literal`[‘Grinold-Kahn’, ‘Menchero-Davis’]	No	`'Menchero-Davis'`
`normalize_holdings`	`bool`	No	`True`
`portfolio_hierarchy_settings`	`PortfolioHierarchySettings`	Yes
`predicted_beta_basis`	`Literal`[‘active’, ‘total’]	No	`'total'`
`report_type`	`Literal`[‘xsr’]	No	`'xsr'`
`rescale_bench`	`bool`	No	`True`

field analytics_space: Literal['absolute', 'active', 'benchmark'] [Optional]#: The book the report decomposes: the portfolio (‘absolute’), the portfolio minus its benchmark (‘active’), or the benchmark (‘benchmark’). Every column describes that book, so in ‘active’ an Exposure is an active exposure.

field annualize: bool [Optional]#

field backfill_holdings: bool [Optional]#

field calendar: CalendarSettings [Optional]#

field currency: str | None [Optional]#

field factor_cov_settings: FactorCovarianceSettings [Optional]#: Settings for the factor covariance matrix forecasts.

field factor_model_settings: str | int | FactorRiskModelSettings [Required]#: The factor risk model to run the report on: either inline settings or a reference (name or id) to saved factor risk model settings.

field idio_vol_settings: IdioVolSettings [Optional]#: Settings for the idiosyncratic volatility matrix forecasts.

field name_contribution_basis: Literal['Grinold-Kahn', 'Menchero-Davis'] [Optional]#: Per-name Contribution split. ‘Grinold-Kahn’ uses the raw asset exposure; ‘Menchero-Davis’ uses the benchmark-relative exposure (asset minus benchmark) per portfolio member when analytics_space=’active’. In currency (normalize_holdings=False) without rescale_bench a member’s active book is not self-financing and the raw split is used. Other spaces use the raw split.

field normalize_holdings: bool [Optional]#: Whether each book is expressed in weights rather than in currency. Decomposed sleeve rows under one fund-of-funds root (e.g. ‘mmf1:p1’, ‘mmf1:{REST}’) are then contributions to that root: their Exposure, Contribution and Beta are measured against the root’s whole book and add up to it, while Volatility remains the standalone risk of each sleeve’s own normalized direction. Each sleeve brings its own benchmark at its NAV, and the root’s benchmark is the NAV-weighted mix of its sleeves’. Mixed-root groups, and every query with normalize_holdings=False, are measured against their own grouped book.

field portfolio_hierarchy_settings: PortfolioHierarchySettings [Required]#

field predicted_beta_basis: Literal['active', 'total'] [Optional]#: Which book predicted Beta’s covariance with the benchmark is taken on: ‘total’ the total portfolio book, ‘active’ the active (portfolio-minus-benchmark) book. Applies in absolute and active analytics space; not applicable in benchmark space.

field report_type: Literal['xsr'] [Optional]#: Report type discriminator

field rescale_bench: bool [Optional]#: Whether each benchmark is scaled to its portfolio’s NAV. Applies only when normalize_holdings is off; normalized reports always carry each benchmark onto its portfolio’s NAV and ignore this value.