bayesline.api.equity.FactorRiskModelSettings#
- pydantic model bayesline.api.equity.FactorRiskModelSettings#
Define all settings needed to build a factor risk model.
Show JSON schema
{ "title": "FactorRiskModelSettings", "description": "Define all settings needed to build a factor risk model.", "type": "object", "properties": { "universe": { "description": "The universe to build the factor risk model on.", "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "$ref": "#/$defs/UniverseSettings" } ] }, "maxItems": 1, "minItems": 1, "title": "Universe", "type": "array" }, "exposures": { "default": [ { "exposures": [] } ], "description": "The exposures to build the factor risk model on.", "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "$ref": "#/$defs/ExposureSettings" } ] }, "minItems": 1, "title": "Exposures", "type": "array" }, "modelconstruction": { "default": [ { "currency": "USD", "weights": "SqrtCap", "estimation_universe": null, "return_clip_bounds": [ -0.1, 0.1 ], "thin_category_shrinkage": {}, "thin_category_shrinkage_overrides": {}, "zero_sum_constraints": {}, "known_factor_map": {}, "fx_convert_returns": true } ], "description": "The model construction settings to use for the factor risk model.", "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "$ref": "#/$defs/ModelConstructionSettings" } ] }, "minItems": 1, "title": "Modelconstruction", "type": "array" }, "halflife_idio_vra": { "anyOf": [ { "exclusiveMinimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "The half-life for the idio adjustment. If None, no adjustment is applied.", "title": "Halflife Idio Vra" } }, "$defs": { "CalendarSettings": { "additionalProperties": false, "description": "Define the settings for the calendar.", "properties": { "dataset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The name of the underlying dataset to use. If none is given then the configured default dataset is used.", "examples": [ "Bayesline-US" ], "title": "Dataset" }, "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" }, "CategoricalExposureGroupSettings": { "additionalProperties": false, "description": "The settings for a categorical exposure group.\n\nCategorical exposures are exposures to a categorical variable, e.g. industry,\ncountry, etc. For example, an asset exposure may be to a single industry factor,\nand we say the exposure is to the industry category factor \"Materials\". The exposure\nitself may be continuous (e.g. not 0.0 or 1.0), and an asset may be exposed to\nmultiple industry factors (but typically not all of them). The distinction with\ncontinuous exposures is primarily in the settings that are available.", "properties": { "exposure_type": { "const": "categorical", "default": "categorical", "title": "Exposure Type", "type": "string" }, "hierarchy": { "description": "The hierarchy to use for the categorical exposures. This is either aHierarchyLevel or HierarchyGroups object. If a string is passed, the value is converted to a HierarchyLevel of that hierarchy with level=1.", "discriminator": { "mapping": { "groups": "#/$defs/HierarchyGroups", "level": "#/$defs/HierarchyLevel" }, "propertyName": "hierarchy_type" }, "examples": [ "trbc", { "hierarchy_type": "level", "level": 2, "name": "trbc" }, { "groupings": { "MyGroup1": [ "Energy" ], "MyGroup2": [ "Materials", "Chemicals" ] }, "hierarchy_type": "groups", "name": "style" } ], "oneOf": [ { "$ref": "#/$defs/HierarchyLevel" }, { "$ref": "#/$defs/HierarchyGroups" } ], "title": "Hierarchy" }, "factor_group": { "default": "", "description": "By default, the name of the factor group will be the name of the hierarchy. But we can override this by specifying an alias here.", "examples": [ "industry", "some_country_group" ], "title": "Factor Group", "type": "string" }, "include": { "anyOf": [ { "const": "All", "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "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": "CategoricalExposureGroupSettings", "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" }, "ContinuousExposureGroupSettings": { "additionalProperties": false, "description": "The settings for a continuous exposure group.\n\nContinuous exposures are exposures that are measured on a continuous scale,\ne.g. market, size, momentum, etc., and are typically available for most assets.", "properties": { "exposure_type": { "const": "continuous", "default": "continuous", "title": "Exposure Type", "type": "string" }, "hierarchy": { "description": "The hierarchy to use for the continuous exposures. This is either aHierarchyLevel or HierarchyGroups object. If a string is passed, the value is converted to a HierarchyLevel of that hierarchy with level=1.", "discriminator": { "mapping": { "groups": "#/$defs/HierarchyGroups", "level": "#/$defs/HierarchyLevel" }, "propertyName": "hierarchy_type" }, "examples": [ "market", { "hierarchy_type": "level", "level": 2, "name": "style" }, { "groupings": { "momentum": [ "mom6" ], "size": [ "size" ] }, "hierarchy_type": "groups", "name": "style" } ], "oneOf": [ { "$ref": "#/$defs/HierarchyLevel" }, { "$ref": "#/$defs/HierarchyGroups" } ], "title": "Hierarchy" }, "factor_group": { "default": "", "description": "By default, the name of the factor group will be the name of the hierarchy. But we can override this by specifying an alias here.", "examples": [ "style", "some_style_group" ], "title": "Factor Group", "type": "string" }, "include": { "anyOf": [ { "const": "All", "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "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": [ [ "momentum" ], "All", [ "Size", "value" ] ], "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": [ [ "momentum" ], [ "Size", "value" ] ], "items": { "type": "string" }, "title": "Exclude", "type": "array" }, "standardize_method": { "default": "none", "description": "The method to use for standardizing the exposures. If 'none', no standardization is applied. If 'equal_weighted', then the exposures are standardized with the mean and standard deviation of the estimation universe.", "enum": [ "none", "equal_weighted" ], "examples": [ "none", "equal_weighted" ], "title": "Standardize Method", "type": "string" } }, "required": [ "hierarchy" ], "title": "ContinuousExposureGroupSettings", "type": "object" }, "ExposureSettings": { "additionalProperties": false, "description": "Defines exposures as hierarchy of selected styles and substyles.", "properties": { "exposures": { "default": [], "description": "The exposures to build the factor risk model on.", "items": { "discriminator": { "mapping": { "categorical": "#/$defs/CategoricalExposureGroupSettings", "continuous": "#/$defs/ContinuousExposureGroupSettings", "interaction": "#/$defs/InteractionExposureGroupSettings" }, "propertyName": "exposure_type" }, "oneOf": [ { "$ref": "#/$defs/ContinuousExposureGroupSettings" }, { "$ref": "#/$defs/CategoricalExposureGroupSettings" }, { "$ref": "#/$defs/InteractionExposureGroupSettings" } ] }, "title": "Exposures", "type": "array" } }, "title": "ExposureSettings", "type": "object" }, "Hierarchy": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "$ref": "#/$defs/Hierarchy" }, "type": "object" } ] }, "HierarchyGroups": { "additionalProperties": false, "description": "The hierarchy decscription for a custom nested grouping of the hierarchy.\n\nThe top level groupings will turn into factors, whereas any nested\ngroupings will be retained for other uses (e.g. risk decomposition).", "properties": { "hierarchy_type": { "const": "groups", "default": "groups", "title": "Hierarchy Type", "type": "string" }, "name": { "description": "\n The name of the hierarchy to use, e.g. 'trbc' or 'continent'.\n If it is not given then the default hierarchy will be used.\n ", "examples": [ "trbc", "continent" ], "minLength": 1, "title": "Name", "type": "string" }, "groupings": { "additionalProperties": { "$ref": "#/$defs/Hierarchy" }, "description": "\n A nested structure of groupings where the keys are the group names\n and the leaf level is a list of hierarchy codes or labels (at any level)\n to include for this group.\n ", "title": "Groupings", "type": "object" } }, "required": [ "name", "groupings" ], "title": "HierarchyGroups", "type": "object" }, "HierarchyLevel": { "additionalProperties": false, "description": "The hierarchy decscription for a level in the hierarchy.\n\nE.g. for industries specifying level `1` would\ncreate top level sector factors.", "properties": { "hierarchy_type": { "const": "level", "default": "level", "title": "Hierarchy Type", "type": "string" }, "name": { "description": "\n The name of the hierarchy to use, e.g. 'trbc' or 'continent'.\n If it is not given then the default hierarchy will be used.\n ", "examples": [ "trbc", "continent" ], "minLength": 1, "title": "Name", "type": "string" }, "level": { "default": 1, "description": "The level of the hierarchy to use, e.g. 1\n to use all level 1 names (i.e. sectors for industries or\n continents for regions) or 2 to use all level 2\n names (i.e. sub-sectors for industries and\n countries for regions).\n ", "examples": [ 1, 2 ], "minimum": 1, "title": "Level", "type": "integer" } }, "required": [ "name" ], "title": "HierarchyLevel", "type": "object" }, "InteractionExposureGroupSettings": { "additionalProperties": false, "description": "The settings for an interaction exposure group.\n\nInteraction exposures are exposures that are a combination of two or more\nexposure groups. For example, we may want to create industry-specific style factors.", "properties": { "exposure_type": { "const": "interaction", "default": "interaction", "title": "Exposure Type", "type": "string" }, "exposure_groups": { "default": [], "description": "The exposure groups to use for the Cartesian product.", "items": { "anyOf": [ { "$ref": "#/$defs/ContinuousExposureGroupSettings" }, { "$ref": "#/$defs/CategoricalExposureGroupSettings" } ] }, "minItems": 2, "title": "Exposure Groups", "type": "array" }, "factor_group": { "default": "", "description": "By default, the name of the factor group will be a concatenation of the names of the exposure groups separated by the a colon.", "examples": [ "industry:style" ], "title": "Factor Group", "type": "string" } }, "title": "InteractionExposureGroupSettings", "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" }, "ModelConstructionSettings": { "additionalProperties": false, "description": "Defines settings to build a factor risk model.", "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": "The ridge-shrinkage penalty for categorical factors with the than 10 assets with strictly positive exposure. Interpolation is used to scale the shrinkage strength (for zero assets) to 0.0 (for 10 assets). The keys are the (categorical) factor groups and the values are the shrinkage penalty.", "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" } }, "title": "ModelConstructionSettings", "type": "object" }, "PortfolioOrganizerSettings": { "additionalProperties": false, "description": "Specifies which portfolios to enable (from different sources).\n\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": { "dataset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The name of the underlying dataset to use for price data needed to forward fill portfolios, obtain corporate actions, etc.If none is given then the configured default dataset is used.", "examples": [ "Bayesline-US" ], "title": "Dataset" }, "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" } }, "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": { "dataset": { "description": "The name of the underlying dataset to use. If none is given then the configured default dataset is used.", "examples": [ "Bayesline-Global" ], "title": "Dataset", "type": "string" }, "id_type": { "default": "bayesid", "description": "The default id type to use for the universe.", "enum": [ "bayesid", "bayesid_core", "ticker", "composite_figi", "cik", "cusip8", "cusip9", "isin", "sedol6", "sedol7", "proxy", "name" ], "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 " } }, "required": [ "dataset" ], "title": "UniverseSettings", "type": "object" } }, "additionalProperties": false, "required": [ "universe" ] }
- Config:
frozen: bool = True
extra: str = forbid
- Fields:
exposures (list[str | int | bayesline.api._src.equity.exposure_settings.ExposureSettings])halflife_idio_vra (int | None)modelconstruction (list[str | int | bayesline.api._src.equity.modelconstruction_settings.ModelConstructionSettings])universe (list[str | int | bayesline.api._src.equity.universe_settings.UniverseSettings])
- Validators:
check_list_lengths»all fieldsvalidate_modelconstruction»modelconstruction
- field universe: Annotated[list[str | int | UniverseSettings], BeforeValidator(_ensure_list), Field(description='The universe to build the factor risk model on.', min_length=1, max_length=1), SettingsTypeMetaData[list[str | int | UniverseSettings]](references=UniverseSettings, extractor=lambda x: [r for r in x if not isinstance(r, UniverseSettings)])] [Required]#
The universe to build the factor risk model on.
- Constraints:
func = <function _ensure_list at 0x7fe2ecac6160>
json_schema_input_type = PydanticUndefined
min_length = 1
max_length = 1
references = <class ‘bayesline.api._src.equity.universe_settings.UniverseSettings’>
extractor = <function <lambda> at 0x7fe2ecac6c00>
- Validated by:
check_list_lengths
- field exposures: Annotated[list[str | int | ExposureSettings], BeforeValidator(_ensure_list), Field(description='The exposures to build the factor risk model on.', min_length=1), SettingsTypeMetaData[str | int | ExposureSettings](references=ExposureSettings, extractor=lambda x: [r for r in x if not isinstance(r, ExposureSettings)])] = [ExposureSettings(exposures=[])]#
The exposures to build the factor risk model on.
- Constraints:
func = <function _ensure_list at 0x7fe2ecac6160>
json_schema_input_type = PydanticUndefined
min_length = 1
references = <class ‘bayesline.api._src.equity.exposure_settings.ExposureSettings’>
extractor = <function <lambda> at 0x7fe2ecac6ca0>
- Validated by:
check_list_lengths
- field modelconstruction: Annotated[list[str | int | ModelConstructionSettings], BeforeValidator(_ensure_list), Field(description='The model construction settings to use for the factor risk model.', min_length=1), SettingsTypeMetaData[str | int | ModelConstructionSettings](references=ModelConstructionSettings, extractor=lambda x: [r for r in x if not isinstance(r, ModelConstructionSettings)])] = [ModelConstructionSettings(currency='USD', weights='SqrtCap', estimation_universe=None, return_clip_bounds=(-0.1, 0.1), thin_category_shrinkage={}, thin_category_shrinkage_overrides={}, zero_sum_constraints={}, known_factor_map={}, fx_convert_returns=True)]#
The model construction settings to use for the factor risk model.
- Constraints:
func = <function _ensure_list at 0x7fe2ecac6160>
json_schema_input_type = PydanticUndefined
min_length = 1
references = <class ‘bayesline.api._src.equity.modelconstruction_settings.ModelConstructionSettings’>
extractor = <function <lambda> at 0x7fe2ecac6d40>
- Validated by:
check_list_lengthsvalidate_modelconstruction
- field halflife_idio_vra: PositiveInt | None = None#
The half-life for the idio adjustment. If None, no adjustment is applied.
- Validated by:
check_list_lengths
- 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.
Get the menu type for this settings object.
Returns#
- type[SettingsMenuType]
The menu type for this settings object.
- validator check_list_lengths FactorRiskModelSettings » all fields#
- validator validate_modelconstruction list[str | int | ModelConstructionSettings] » modelconstruction#
- describe(menu: FactorRiskModelSettingsMenu) str#
Describe the settings.
Parameters#
- menuFactorRiskModelSettingsMenu
The settings menu to use to construct the description.
Returns#
- str
A description of the settings.