bayesline.api.equity.ModelConstructionSettings

pydantic model bayesline.api.equity.ModelConstructionSettings

Defines settings to build a factor risk model.

Show JSON schema

{
   "title": "ModelConstructionSettings",
   "description": "Defines settings to build a factor risk model.",
   "type": "object",
   "properties": {
      "currency": {
         "default": "USD",
         "description": "The currency of the factor risk model.",
         "examples": [
            "USD",
            "EUR"
         ],
         "title": "Currency",
         "type": "string"
      },
      "weights": {
         "default": "SqrtCap",
         "description": "The regression weights used for the factor risk model.",
         "enum": [
            "SqrtCap",
            "InvIdioVar"
         ],
         "examples": [
            "SqrtCap",
            "InvIdioVar"
         ],
         "title": "Weights",
         "type": "string"
      },
      "estimation_universe": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "integer"
            },
            {
               "$ref": "#/$defs/UniverseSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The universe settings to use for the estimation universe.",
         "title": "Estimation Universe"
      },
      "return_clip_bounds": {
         "default": [
            -0.1,
            0.1
         ],
         "description": "The bounds for the return clipping.",
         "examples": [
            [
               -0.1,
               0.1
            ],
            [
               null,
               null
            ]
         ],
         "maxItems": 2,
         "minItems": 2,
         "prefixItems": [
            {
               "anyOf": [
                  {
                     "maximum": 0,
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ]
            },
            {
               "anyOf": [
                  {
                     "minimum": 0,
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ]
            }
         ],
         "title": "Return Clip Bounds",
         "type": "array"
      },
      "thin_category_shrinkage": {
         "additionalProperties": {
            "minimum": 0,
            "type": "number"
         },
         "description": "Minimum effective number of assets (n_eff) for categorical factor groups. Factors with n_eff below this threshold get L2 shrinkage toward zero, with strength proportional to (threshold - n_eff). n_eff is the inverse HHI of regression-weight-scaled exposures. Keys are factor group names, values are n_eff thresholds. Interaction groups automatically inherit the threshold from their categorical parent component.",
         "title": "Thin Category Shrinkage",
         "type": "object"
      },
      "thin_category_shrinkage_overrides": {
         "additionalProperties": {
            "minimum": 0,
            "type": "number"
         },
         "description": "The shrinkage strength override for the factor risk model. The keys are the tuples of (categorical) factor groups and factor names and the values are the shrinkage penalty overrides.",
         "title": "Thin Category Shrinkage Overrides",
         "type": "object"
      },
      "zero_sum_constraints": {
         "additionalProperties": {
            "enum": [
               "none",
               "equal_weights",
               "mcap_weighted"
            ],
            "type": "string"
         },
         "description": "Whether to apply a zero-sum constraint to the categorical exposures. If the category exposures are exhaustive and sum to one, then implicitly a dummy variable trap is present. This can be avoided by creating a constraint on the factor returns. This means the interpretation of the categorical factor returns is 'in excess of' the market. If 'none', no constraint is applied (for example if we do not have a market factor). If 'equal_weights' or 'mcap_weighted', then the categorical factor returns are constrained to sum to zero, either market-cap weighted or not. For all categorical factor groups, a value must be provided.",
         "examples": [
            {
               "industry": [
                  "none"
               ]
            },
            {
               "country": [
                  "mcap_weighted"
               ],
               "industry": [
                  "equal_weights"
               ]
            }
         ],
         "title": "Zero Sum Constraints",
         "type": "object"
      },
      "known_factor_map": {
         "additionalProperties": {
            "type": "string"
         },
         "description": "A mapping from tuple of factor groups and factor names (labels) to known series. These factors will have fixed returns derived from the series.",
         "title": "Known Factor Map",
         "type": "object"
      },
      "fx_convert_returns": {
         "default": true,
         "description": "Whether to convert the asset returns to the currency of the factor model.",
         "title": "Fx Convert Returns",
         "type": "boolean"
      }
   },
   "$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"
      },
      "CategoricalFilterSettings": {
         "additionalProperties": false,
         "description": "Specify include and exclude filters for categorical codes.\n\nExamples of categorical codes are industries or countries. Assets are included if\nthey are part of at least one include and not part of any exclude.\n\nBy default all codes for the given hierarchy are included.",
         "properties": {
            "hierarchy": {
               "description": "The categorical hierarchy to use.",
               "examples": [
                  "trbc"
               ],
               "minLength": 1,
               "title": "Hierarchy",
               "type": "string"
            },
            "include": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "const": "All",
                     "type": "string"
                  }
               ],
               "default": "All",
               "description": "Valid industry codes or labels for given hierarchy at any level. If labels are used which may be duplicated, then the code with the highest level is used. If 'All', all codes are included.",
               "examples": [
                  [
                     "3571"
                  ],
                  "All",
                  [
                     "Materials",
                     "1010"
                  ],
                  [
                     "Europe",
                     "CAN"
                  ]
               ],
               "title": "Include"
            },
            "exclude": {
               "description": "Valid industry codes or labels for given hierarchy at any level. If labels are used which may be duplicated, then the code with the lowest level is used.",
               "examples": [
                  [
                     "3571"
                  ],
                  [
                     "Materials",
                     "1010"
                  ],
                  [
                     "JPN"
                  ]
               ],
               "items": {
                  "type": "string"
               },
               "title": "Exclude",
               "type": "array"
            }
         },
         "required": [
            "hierarchy"
         ],
         "title": "CategoricalFilterSettings",
         "type": "object"
      },
      "MCapFilterSettings": {
         "additionalProperties": false,
         "description": "Specify the lower and upper bound for the market cap filter.\n\nBy default the bounds are infinite.",
         "properties": {
            "lower": {
               "default": 0.0,
               "description": "Lower bound of the cap filter in USD.",
               "examples": [
                  10000000000.0
               ],
               "minimum": 0,
               "title": "Lower",
               "type": "number"
            },
            "upper": {
               "default": 1e+20,
               "description": "Upper bound of the cap filter in USD.",
               "examples": [
                  1000000000000.0
               ],
               "exclusiveMinimum": 0.0,
               "minimum": 0,
               "title": "Upper",
               "type": "number"
            }
         },
         "title": "MCapFilterSettings",
         "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"
      },
      "UniverseSettings": {
         "additionalProperties": false,
         "description": "Define an asset universe as a set of regional, industry and market cap filters.",
         "properties": {
            "id_type": {
               "default": "bayesid",
               "description": "The default id type to use for the universe.",
               "examples": [
                  "cusip9",
                  "bayesid"
               ],
               "title": "Id Type",
               "type": "string"
            },
            "calendar": {
               "$ref": "#/$defs/CalendarSettings",
               "description": "The calendar settings to use for the universe."
            },
            "categorical_filters": {
               "description": "\n        Filters that determine which categorical codes to include and exclude in the universe.\n        ",
               "items": {
                  "$ref": "#/$defs/CategoricalFilterSettings"
               },
               "title": "Categorical Filters",
               "type": "array"
            },
            "portfolio_filter": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "integer"
                  },
                  {
                     "$ref": "#/$defs/PortfolioOrganizerSettings"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The portfolio organizer settings to use as an underlying schema of portfolios. Universe will be filtered across the superset of all portfolios.",
               "title": "Portfolio Filter"
            },
            "mcap_filter": {
               "$ref": "#/$defs/MCapFilterSettings",
               "description": "\n        Filters that determine which market caps to include and exclude in the universe.\n        "
            }
         },
         "title": "UniverseSettings",
         "type": "object"
      }
   },
   "additionalProperties": false
}

Config:

• frozen: bool = True

• extra: str = forbid

Fields:

• currency (str)

• estimation_universe (str | int | bayesline.api._src.equity.universe_settings.UniverseSettings | None)

• fx_convert_returns (bool)

• known_factor_map (Mapping[tuple[str, str], str])

• return_clip_bounds (tuple[float | None, float | None])

• thin_category_shrinkage (Mapping[str, float])

• thin_category_shrinkage_overrides (Mapping[tuple[str, str], float])

• weights (Literal['SqrtCap', 'InvIdioVar'])

• zero_sum_constraints (Mapping[str, Literal['none', 'equal_weights', 'mcap_weighted']])

Validators:

• check_valid_weights » weights

field currency: str = 'USD'

The currency of the factor risk model.

Validated by:

• _strip_unknown_on_load

field weights: Literal['SqrtCap', 'InvIdioVar'] = 'SqrtCap'

The regression weights used for the factor risk model.

Validated by:

• _strip_unknown_on_load

• check_valid_weights

field estimation_universe: str | int | UniverseSettings | None = None

The universe settings to use for the estimation universe.

Validated by:

• _strip_unknown_on_load

field return_clip_bounds: tuple[Optional[Annotated[float]], Optional[Annotated[float]]] = (-0.1, 0.1)

The bounds for the return clipping.

Validated by:

• _strip_unknown_on_load

field thin_category_shrinkage: Mapping[str, Annotated[float]] [Optional]

Minimum effective number of assets (n_eff) for categorical factor groups. Factors with n_eff below this threshold get L2 shrinkage toward zero, with strength proportional to (threshold - n_eff). n_eff is the inverse HHI of regression-weight-scaled exposures. Keys are factor group names, values are n_eff thresholds. Interaction groups automatically inherit the threshold from their categorical parent component.

Validated by:

• _strip_unknown_on_load

field thin_category_shrinkage_overrides: Mapping[tuple[str, str], Annotated[float]] [Optional]

The shrinkage strength override for the factor risk model. The keys are the tuples of (categorical) factor groups and factor names and the values are the shrinkage penalty overrides.

Validated by:

• _strip_unknown_on_load

field zero_sum_constraints: Mapping[str, Literal['none', 'equal_weights', 'mcap_weighted']] [Optional]

Whether to apply a zero-sum constraint to the categorical exposures. If the category exposures are exhaustive and sum to one, then implicitly a dummy variable trap is present. This can be avoided by creating a constraint on the factor returns. This means the interpretation of the categorical factor returns is ‘in excess of’ the market. If ‘none’, no constraint is applied (for example if we do not have a market factor). If ‘equal_weights’ or ‘mcap_weighted’, then the categorical factor returns are constrained to sum to zero, either market-cap weighted or not. For all categorical factor groups, a value must be provided.

Validated by:

• _strip_unknown_on_load

field known_factor_map: Mapping[tuple[str, str], str] [Optional]

A mapping from tuple of factor groups and factor names (labels) to known series. These factors will have fixed returns derived from the series.

Validated by:

• _strip_unknown_on_load

field fx_convert_returns: bool = True

Whether to convert the asset returns to the currency of the factor model.

Validated by:

• _strip_unknown_on_load

get_references() → Sequence[str | int]

Get references for this settings object.

Returns

Sequence[str | int]

A sequence of references (strings or integers) for this settings object.

property menu_type: type[ModelConstructionSettingsMenu]

Get the menu type for this settings object.

Returns

type[M]

The menu type for this settings object.

validator check_valid_weights → Literal['SqrtCap', 'InvIdioVar']  »  weights

describe(menu: ModelConstructionSettingsMenu) → str

Describe the available settings.

Parameters

menuModelConstructionSettingsMenu

The menu to get context information from.

Returns

str

The description of the model construction settings.