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": "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"
      }
   },
   "$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"
      },
      "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": "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
}

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.

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

The regression weights used for the factor risk model.

Validated by:

• check_valid_weights

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

The universe settings to use for the estimation universe.

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

The bounds for the return clipping.

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

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.

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.

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.

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.

field fx_convert_returns: bool = True

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

property menu_type: type[ModelConstructionSettingsMenu]

Get the menu type for this settings object.

Returns

type[SettingsMenuType]

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.