boosted.api.api_type

   1# Copyright (C) 2020 Gradient Boosted Investments, Inc. - All Rights Reserved
   2
   3import copy
   4import datetime as dt
   5import json
   6import logging
   7import re
   8import string
   9from collections import defaultdict
  10from dataclasses import dataclass
  11from enum import Enum
  12from typing import Dict, List, Literal, Optional, Union
  13
  14import numpy as np
  15import pandas as pd
  16
  17logger = logging.getLogger("boosted.api.api_type")
  18
  19BoostedDate = Union[dt.date, str]
  20
  21
  22class Status(Enum):
  23    UNKNOWN = 0
  24    FAIL = 1
  25    SUCCESS = 2
  26
  27
  28class DataAddType(Enum):
  29    CREATION = 1
  30    HISTORICAL = 2
  31    LIVE = 3
  32
  33    def __str__(self):
  34        if self.name == "CREATION":
  35            return "CREATION"
  36        elif self.name == "HISTORICAL":
  37            return "HISTORICAL"
  38        elif self.name == "LIVE":
  39            return "LIVE"
  40
  41
  42class ChunkStatus(Enum):
  43    PROCESSING = "PROCESSING"
  44    ABORTED = "ABORTED"
  45    SUCCESS = "SUCCESS"
  46    WARNING = "WARNING"
  47    ERROR = "ERROR"
  48
  49
  50class DataSetType(Enum):
  51    UNKNOWN = 0
  52    STOCK = 1
  53    GLOBAL = 2
  54    STRATEGY = 3
  55    SECURITIES_DAILY = 4
  56
  57    def __str__(self):
  58        if self.name == "STOCK":
  59            return "STOCK"
  60        elif self.name == "GLOBAL":
  61            return "GLOBAL"
  62        elif self.name == "STRATEGY":
  63            return "STRATEGY"
  64        elif self.name == "SECURITIES_DAILY":
  65            return "SECURITIES_DAILY"
  66        else:
  67            return "UNKNOWN"
  68
  69
  70class DataSetSubType(Enum):
  71    UNKNOWN = 0
  72    DENSE = 1
  73    SPARSE_HIST = 2
  74    SPARSE_FWD = 3
  75
  76    def __str__(self):
  77        if self.name == "DENSE":
  78            return "DENSE"
  79        elif self.name == "SPARSE_HIST":
  80            return "SPARSE_HIST"
  81        elif self.name == "SPARSE_FWD":
  82            return "SPARSE_FWD"
  83        else:
  84            return "UNKNOWN"
  85
  86
  87class DataSetFrequency(Enum):
  88    UNKNOWN = 0
  89    DAILY = 1
  90    WEEKLY = 2
  91    MONTHLY = 3
  92    QUARTERLY = 4
  93    SEMIANNUAL = 5
  94    ANNUAL = 6
  95
  96    def __str__(self):
  97        if self.name == "DAILY":
  98            return "DAILY"
  99        elif self.name == "WEEKLY":
 100            return "WEEKLY"
 101        elif self.name == "MONTHLY":
 102            return "MONTHLY"
 103        elif self.name == "QUARTERLY":
 104            return "QUARTERLY"
 105        elif self.name == "SEMIANNUAL":
 106            return "SEMIANNUAL"
 107        elif self.name == "ANNUAL":
 108            return "ANNUAL"
 109        else:
 110            return "UNKNOWN"
 111
 112
 113class ThemeUniverse(Enum):
 114    XIC = "XIC Membership (TSX Composite)"  # bd4163fd-ad77-4412-a250-a2c9e0c13802
 115    SPY = "SPY Membership (S&P 500)"  # 4e5f2fd3-394e-4db9-aad3-5c20abf9bf3c
 116    QQQ = "QQQ Membership (Nasdaq)"  # d532609b-620a-425b-b8f1-e94f51e0394d
 117    IWM = "IWM Membership (Russell 2000)"  # 5ad0a5b3-d4e2-439e-af57-6ea5475c19e8
 118    IWB = "IWB Membership (Russell 1000)"  # ed851cea-f19a-45b2-8948-f6cc3503d087
 119    IWV = "IWV Membership (iShares Russell 3000 ETF)"  # c122c187-bb0d-4207-87a3-e06f0b877bc9
 120    EXSA = "EXSA Membership (Stoxx 600)"  # e160fe15-038b-44ea-be12-1cc1054a26d8
 121    ASHR = "ASHR Membership (CSI 300)"  # ee1f70fd-1010-4a90-b2fa-be633ad3d163
 122
 123    @classmethod
 124    def get_ticker_from_name(cls, name: str) -> Optional[str]:
 125        for key, value in cls.__members__.items():
 126            if value.value == name:
 127                return key
 128
 129        return None
 130
 131
 132class Language(str, Enum):
 133    ENGLISH = "en"
 134    CHINESE = "zh-CN"
 135
 136
 137class NewsHorizon(Enum):
 138    ONE_DAY = "1D"
 139    ONE_WEEK = "1W"
 140    ONE_MONTH = "1M"
 141
 142
 143class ColumnRole(Enum):
 144    UNKNOWN = 0
 145    VARIABLE = 1
 146    GOAL = 2
 147    METRIC = 3
 148    IDENTIFIER = 4
 149
 150    def __str__(self):
 151        if self.name == "VARIABLE":
 152            return "VARIABLE"
 153        elif self.name == "GOAL":
 154            return "GOAL"
 155        elif self.name == "METRIC":
 156            return "METRIC"
 157        elif self.name == "IDENTIFIER":
 158            return "IDENTIFIER"
 159        else:
 160            return "UNKNOWN"
 161
 162
 163class ColumnSubRole(Enum):
 164    UNKNOWN = 0
 165    GBI_ID = 1
 166    ISIN = 2
 167    GVKEY = 3
 168    IID = 4
 169    SYMBOL = 5
 170    COUNTRY = 6
 171    CURRENCY = 7
 172    DATE = 8
 173    COMPANY_NAME = 9
 174    REPORT_DATE = 10
 175    REPORT_PERIOD = 11
 176    CUSTOM_SECURITY = 12
 177
 178    def __str__(self):
 179        if self.name == "GBI_ID":
 180            return "GBI_ID"
 181        elif self.name == "ISIN":
 182            return "ISIN"
 183        elif self.name == "GVKEY":
 184            return "GVKEY"
 185        elif self.name == "IID":
 186            return "IID"
 187        elif self.name == "SYMBOL":
 188            return "SYMBOL"
 189        elif self.name == "COUNTRY":
 190            return "COUNTRY"
 191        elif self.name == "CURRENCY":
 192            return "CURRENCY"
 193        elif self.name == "DATE":
 194            return "DATE"
 195        elif self.name == "COMPANY_NAME":
 196            return "COMPANY_NAME"
 197        elif self.name == "REPORT_DATE":
 198            return "REPORT_DATE"
 199        elif self.name == "REPORT_PERIOD":
 200            return "REPORT_PERIOD"
 201        elif self.name == "CUSTOM_SECURITY":
 202            return "CUSTOM_SECURITY"
 203        else:
 204            return "UNKNOWN"
 205
 206    def get_match(column_name):
 207        def clean_str(name):
 208            translation = str.maketrans("", "", string.punctuation)
 209            clean_name = name.strip().translate(translation).lower()
 210            return re.sub(r"\s+", "", clean_name)
 211
 212        identifiers = [
 213            ColumnSubRole.GBI_ID,
 214            ColumnSubRole.ISIN,
 215            ColumnSubRole.GVKEY,
 216            ColumnSubRole.IID,
 217            ColumnSubRole.SYMBOL,
 218            ColumnSubRole.COUNTRY,
 219            ColumnSubRole.CURRENCY,
 220            ColumnSubRole.COMPANY_NAME,
 221            ColumnSubRole.REPORT_DATE,
 222            ColumnSubRole.REPORT_PERIOD,
 223            ColumnSubRole.CUSTOM_SECURITY,
 224        ]
 225
 226        for identifier in identifiers:
 227            if clean_str(str(identifier)) == clean_str(column_name):
 228                return identifier
 229        return None
 230
 231
 232class ColumnValueType(Enum):
 233    UNKNOWN = 0
 234    NUMBER = 1
 235    STRING = 2
 236
 237    def __str__(self):
 238        if self.name == "UNKNOWN":
 239            return "UNKNOWN"
 240        elif self.name == "NUMBER":
 241            return "NUMBER"
 242        elif self.name == "STRING":
 243            return "STRING"
 244        else:
 245            return "UNKNOWN"
 246
 247
 248class CustomNamespaceVariableRole(Enum):
 249    UNKNOWN = "UNKNOWN"
 250    DAILY_OPEN = "DAILY_OPEN"
 251    DAILY_CLOSE = "DAILY_CLOSE"  # mandatory
 252    DAILY_VWAP = "DAILY_VWAP"
 253    DAILY_VOLUME = "DAILY_VOLUME"
 254    DAILY_HIGH = "DAILY_HIGH"
 255    DAILY_LOW = "DAILY_LOW"
 256    DAILY_BID = "DAILY_BID"
 257    DAILY_ASK = "DAILY_ASK"
 258    DAILY_MCAP = "DAILY_MCAP"
 259
 260    def get_match(column_name):
 261        def clean_str(name):
 262            translation = str.maketrans("", "", string.punctuation)
 263            clean_name = name.strip().translate(translation).lower()
 264            return re.sub(r"\s+", "", clean_name)
 265
 266        identifiers = [
 267            CustomNamespaceVariableRole.DAILY_OPEN,
 268            CustomNamespaceVariableRole.DAILY_CLOSE,
 269            CustomNamespaceVariableRole.DAILY_VWAP,
 270            CustomNamespaceVariableRole.DAILY_VOLUME,
 271            CustomNamespaceVariableRole.DAILY_HIGH,
 272            CustomNamespaceVariableRole.DAILY_LOW,
 273            CustomNamespaceVariableRole.DAILY_BID,
 274            CustomNamespaceVariableRole.DAILY_ASK,
 275            CustomNamespaceVariableRole.DAILY_MCAP,
 276        ]
 277
 278        for identifier in identifiers:
 279            if clean_str(str(identifier)) == clean_str(column_name):
 280                return identifier
 281        return None
 282
 283    def __str__(self):
 284        return self.value
 285
 286
 287class ColumnConfig:
 288    def __init__(
 289        self,
 290        name=None,
 291        role=None,
 292        sub_role=None,
 293        value_type=ColumnValueType.NUMBER,
 294        description="",
 295        investment_horizon=None,
 296        custom_namespace_variable_role=None,
 297    ):
 298        self.name = name
 299        self.role = role
 300        self.sub_role = sub_role
 301        self.value_type = value_type
 302        # More value_types will be supported in the future.
 303        self.description = description
 304        self.investment_horizon = investment_horizon
 305        self.custom_namespace_variable_role = custom_namespace_variable_role
 306
 307    def __str__(self):
 308        return (
 309            'Name: "{0}", Role: {1}, SubRole: {2}, Value type: {3}, '
 310            + "Desc: {4} IH: {5} CNSRole: {6}."
 311        ).format(
 312            self.name,
 313            self.role,
 314            self.sub_role,
 315            self.value_type,
 316            self.description,
 317            self.investment_horizon,
 318            self.custom_namespace_variable_role,
 319        )
 320
 321    def __repr__(self):
 322        return self.__str__()
 323
 324
 325class StrategyConfig:
 326    def __init__(self, name=None, source_name=None):
 327        self.name = name
 328        self.source_name = source_name
 329
 330    def __str__(self):
 331        return 'Name: "{0}", Source Name: {1}.'.format(self.name, self.source_name)
 332
 333    def __repr__(self):
 334        return self.__str__()
 335
 336
 337class BoostedAPIException(Exception):
 338    def __init__(self, value, data=None):
 339        self.value = value
 340        self.data = data
 341
 342    def __str__(self):
 343        return repr(self.value)
 344
 345
 346class BoostedDataSetSchemaException(Exception):
 347    def __init__(self, value, data=None):
 348        self.value = value
 349        self.data = data
 350
 351    def __str__(self):
 352        return repr(self.value)
 353
 354
 355class DataSetConfig:
 356    def __init__(
 357        self,
 358        name,
 359        datasetType=DataSetType.STOCK,
 360        datasetSubType=DataSetSubType.DENSE,
 361        datasetFrequency=DataSetFrequency.DAILY,
 362    ):
 363        self.name = name
 364        self.type = datasetType
 365        self.subtype = datasetSubType
 366        self.frequency = datasetFrequency
 367        self.columns = []
 368        self.strategies = []
 369
 370    def addColumn(self, columnConfig):
 371        self.columns.append(columnConfig)
 372
 373    def addStrategy(self, strategyConfig):
 374        self.strategies.append(strategyConfig)
 375
 376    def __getColumnByName(self, col_name):
 377        for column in self.columns:
 378            if col_name == column.name:
 379                return column
 380        raise BoostedDataSetSchemaException(f"Unable to find column {col_name}")
 381
 382    def updateColumnToGoal(self, col_name, investment_horizon):
 383        column = self.__getColumnByName(col_name)
 384        column.role = ColumnRole.GOAL
 385        column.investment_horizon = int(investment_horizon)
 386
 387    def updateColumnToMetric(self, col_name):
 388        column = self.__getColumnByName(col_name)
 389        column.role = ColumnRole.METRIC
 390
 391    def updateColumnToVariable(self, col_name):
 392        column = self.__getColumnByName(col_name)
 393        column.role = ColumnRole.VARIABLE
 394
 395    def __validateSchema(self):
 396        num_goals = 0
 397        num_metrics = 0
 398        dt = self.type
 399        dst = self.subtype
 400        dsf = self.frequency
 401        if len(self.columns) == 0:
 402            msg = "No feature columns exist."
 403            raise BoostedDataSetSchemaException(msg)
 404
 405        if dst in [DataSetSubType.SPARSE_HIST, DataSetSubType.SPARSE_FWD]:
 406            if dsf not in [DataSetFrequency.QUARTERLY]:
 407                msg = f"{dsf} frequency is not supported for {dst} sub data"
 408                raise BoostedDataSetSchemaException(msg)
 409            if dt not in [DataSetType.STOCK]:
 410                msg = f"{dst} subtype is not supported for {dt} data"
 411                raise BoostedDataSetSchemaException(msg)
 412
 413        for column in self.columns:
 414            if column.role == ColumnRole.GOAL:
 415                ih = column.investment_horizon
 416                gn = column.name
 417                if dt == DataSetType.GLOBAL:
 418                    msg = f"{dt} data can not have {ColumnRole.GOAL} type"
 419                    raise BoostedDataSetSchemaException(msg)
 420                if not isinstance(ih, int):
 421                    msg = f"Investment horizon for {gn} must be an integer"
 422                    raise BoostedDataSetSchemaException(msg)
 423                if ih < 1 or ih > 252:
 424                    msg = f"Investment horizon must be between 1 and 252 for {gn}"
 425                    raise BoostedDataSetSchemaException(msg)
 426                num_goals += 1
 427            elif column.role == ColumnRole.METRIC:
 428                if dt in [DataSetType.GLOBAL, DataSetType.STOCK]:
 429                    msg = f"{dt} data can not have {ColumnRole.METRIC} type"
 430                    raise BoostedDataSetSchemaException(msg)
 431                num_metrics += 1
 432
 433        if dt == DataSetType.STRATEGY:
 434            if num_goals == 0:
 435                msg = "Independent data requires at least one goal."
 436                raise BoostedDataSetSchemaException(msg)
 437            if num_metrics == 0:
 438                msg = "Independent data requires at least one metric."
 439                raise BoostedDataSetSchemaException(msg)
 440            if len(self.strategies) <= 1:
 441                msg = "Independent data requires more than 1 strategy"
 442                raise BoostedDataSetSchemaException(msg)
 443
 444    def toDict(self):
 445        self.__validateSchema()
 446        config = {}
 447        config["name"] = self.name
 448        config["type"] = str(self.type)
 449        config["subType"] = str(self.subtype)
 450        config["frequency"] = str(self.frequency)
 451        featureList = []
 452        for i, f in enumerate(self.columns):
 453            fm = {}
 454            fm["name"] = f.name
 455            fm["description"] = f.description
 456            fm["type"] = str(f.role)
 457            fm["role"] = str(f.role)
 458            fm["subRole"] = str(f.sub_role) if f.sub_role is not None else None
 459            fm["valuesType"] = str(f.value_type)
 460            fm["columnName"] = f.name
 461            fm["investmentHorizon"] = f.investment_horizon
 462            fm["customNamespaceDatasetVariableRole"] = (
 463                str(f.custom_namespace_variable_role)
 464                if f.custom_namespace_variable_role is not None
 465                else None
 466            )
 467            featureList.append(fm)
 468        config["features"] = featureList
 469        strategyList = []
 470        for i, s in enumerate(self.strategies):
 471            sm = {}
 472            sm["name"] = s.name
 473            sm["sourceName"] = s.source_name
 474            strategyList.append(sm)
 475        config["strategies"] = strategyList
 476        return config
 477
 478    def __str__(self):
 479        a = ""
 480        a += "Name: {0}\n".format(self.name)
 481        a += "Columns: \n"
 482        for c in self.columns:
 483            a += "  {0}\n".format(c)
 484        return a
 485
 486    def __repr__(self):
 487        return self.__str__()
 488
 489    def fromDict(schema):
 490        subtype = DataSetSubType[schema.get("subtype", str(DataSetSubType.DENSE))]
 491        frequency = DataSetFrequency[schema.get("frequency", str(DataSetFrequency.DAILY))]
 492        config = DataSetConfig(
 493            schema["name"],
 494            datasetType=DataSetType[schema["type"]],
 495            datasetSubType=subtype,
 496            datasetFrequency=frequency,
 497        )
 498        # two things left to fill in - strategies and columns
 499        for strategy_data in schema["strategies"]:
 500            config.addStrategy(
 501                StrategyConfig(name=strategy_data["name"], source_name=strategy_data["sourceName"])
 502            )
 503
 504        for feature_data in schema["features"]:
 505            config.addColumn(
 506                ColumnConfig(
 507                    name=feature_data["columnName"],
 508                    description=feature_data["description"] or "",
 509                    investment_horizon=feature_data["investmentHorizon"],
 510                    value_type=(
 511                        ColumnValueType[feature_data["valuesType"]]
 512                        if feature_data["valuesType"] is not None
 513                        else ColumnValueType.NUMBER
 514                    ),
 515                    role=(
 516                        ColumnRole[feature_data["role"]]
 517                        if feature_data["role"] is not None
 518                        else None
 519                    ),
 520                    sub_role=(
 521                        ColumnSubRole[feature_data["subRole"]]
 522                        if feature_data["subRole"] is not None
 523                        else None
 524                    ),
 525                    custom_namespace_variable_role=(
 526                        CustomNamespaceVariableRole[
 527                            feature_data["customNamespaceDatasetVariableRole"]
 528                        ]
 529                        if feature_data["customNamespaceDatasetVariableRole"] is not None
 530                        else None
 531                    ),
 532                )
 533            )
 534
 535        config.__validateSchema()
 536        return config
 537
 538
 539class GbiIdSecurityException(Exception):
 540    def __init__(self, value, data=None):
 541        self.value = value
 542        self.data = data
 543
 544    def __str__(self):
 545        return repr(self.value)
 546
 547
 548class GbiIdTickerISIN:
 549    def __init__(self, gbi_id: int, ticker: str, isin: str):
 550        self.gbi_id = int(gbi_id)
 551        self.ticker = ticker
 552        self.isin = isin
 553
 554    def __str__(self):
 555        return "(gbi_id: {0}, ticker: {1}, isin: {2})".format(self.gbi_id, self.ticker, self.isin)
 556
 557    def __repr__(self):
 558        return self.__str__()
 559
 560
 561class GbiIdSecurity:
 562    def __init__(self, gbi_id, isin_country_currency_date, ticker, company_name):
 563        self.gbi_id = gbi_id
 564        self.isin_info = isin_country_currency_date
 565        self.ticker = ticker
 566        self.company_name = company_name
 567
 568    def __str__(self):
 569        return '\n(gbi_id: "{0}", isin_info: {1}, ticker: {2}, company_name: {3})'.format(
 570            self.gbi_id, self.isin_info.__str__(), self.ticker, self.company_name
 571        )
 572
 573    def __repr__(self):
 574        return self.__str__()
 575
 576    def __eq__(self, __o: object) -> bool:
 577        return self.gbi_id == __o.gbi_id
 578
 579    def __hash__(self):
 580        return hash(self.gbi_id)
 581
 582
 583class DateIdentCountryCurrencyException(Exception):
 584    def __init__(self, value, data=None):
 585        self.value = value
 586        self.data = data
 587
 588    def __str__(self):
 589        return repr(self.value)
 590
 591
 592# for backward compatibility
 593class DateIsinCountryCurrencyException(DateIdentCountryCurrencyException):
 594    pass
 595
 596
 597class DateIdentCountryCurrency:
 598    def __init__(
 599        self,
 600        date: str,
 601        identifier: str,
 602        country: Optional[str] = None,
 603        currency: Optional[str] = None,
 604        id_type: ColumnSubRole = ColumnSubRole.ISIN,
 605    ):
 606        self.date = date
 607        self.identifier = identifier
 608        self.id_type = id_type
 609        self.country = country
 610        self.currency = currency
 611        self.__validateInput()
 612
 613    def __str__(self):
 614        return '(date: "{0}", identifier: "{1}", country: {2}, currency: {3})'.format(
 615            self.date, self.identifier, self.country, self.currency
 616        )
 617
 618    def __repr__(self):
 619        return self.__str__()
 620
 621    def __validateInput(self):
 622        # simply ensure that at least isin and date are filled out.
 623        # country/currency defaults to ANY if not filled out, but
 624        # still is not recommended.
 625        if self.identifier is None or self.date is None:
 626            raise DateIdentCountryCurrencyException(
 627                "ISIN or Date not provided while constructing DateIsinCountryCurrency"
 628            )
 629
 630        if self.id_type not in (ColumnSubRole.ISIN, ColumnSubRole.SYMBOL):
 631            raise DateIdentCountryCurrencyException(f"Invalid ID Type: {self.id_type}")
 632
 633        def check_is_str(value, fieldname):
 634            if value is not None and not isinstance(value, str):
 635                raise DateIdentCountryCurrencyException(
 636                    f"Field {fieldname} in DateIsinCountryCurrency was not a string."
 637                )
 638
 639        check_is_str(self.date, "date")
 640        check_is_str(self.identifier, "identifier")
 641        check_is_str(self.country, "country")
 642        check_is_str(self.currency, "currency")
 643
 644
 645# for backwards compatibility
 646class DateIsinCountryCurrency(DateIdentCountryCurrency):
 647    def __init__(self, date, isin, country, currency):
 648        super().__init__(date, isin, country, currency, ColumnSubRole.ISIN)
 649        self.isin = isin
 650
 651    def __str__(self):
 652        return '(date: "{0}", isin: "{1}", country: {2}, currency: {3})'.format(
 653            self.date, self.isin, self.country, self.currency
 654        )
 655
 656
 657class IdentifierToColumnMapping:
 658    """
 659    IdentifierToColumnMapping is a mapping from string to boosted.api.api_type.ColumnSubRole.
 660    The key of the mapping corresponds to a CSV column name, and the value corresponds
 661    to the type of identifier that it maps to. Only columns specifying an identifying factor
 662    for the stock needs to be specified (e.g. ISIN, Date, Symbol, Currency)
 663    """
 664
 665    def __init__(self, mapping):
 666        self.mapping = mapping
 667        self.__validateInput()
 668
 669    def __str__(self):
 670        return repr(self.value)
 671
 672    def __validateInput(self):
 673        def validate_key_val(key, val):
 674            if not isinstance(key, str):
 675                raise Exception(f"key in IdentifierToColumnMapping {key} was not a string!")
 676            if not isinstance(val, ColumnSubRole):
 677                raise Exception(f"val in IdentifierToColumnMapping {val} was not a ColumnSubRole!")
 678
 679        for key, val in self.mapping:
 680            validate_key_val(key, val)
 681
 682
 683class PortfolioSettings:
 684    """
 685    This config is a documentation wrapper around a dict representing the portfolio settings json.
 686    Keys missing in the dict provided will fallback to the listed default when updating the
 687    the portfolio settings on the server.
 688
 689    Parameters
 690    ----------
 691    activeRisk: bool
 692        - **Active Risk**:
 693            Set the portfolio optimization parameters to be relative to the score from the stock
 694            universe. i.e. if you set Momentum to 0.5 to 1.0 and the stock universe has a market cap
 695            weighed score of 0.2 then the optimizer will solve for 0.7 to 1.2.
 696        - Constraints:
 697            Boolean value
 698        - Default Value: false
 699
 700    allowCompanyCollisions: bool
 701        - **Allow Multiple Securities Per Company**:
 702            Allows the machine to trade multiple securities (at the same time) for the same company.
 703            If it is ON and a company has listed PREF shares and COMMON shares, both will show up as
 704            tradeable options for that company. If it is OFF then system will try to determine the
 705            "correct" security to trade based on volume, liquidity, and share type.
 706        - Constraints:
 707            Boolean value
 708        - Default Value: true
 709
 710    allowDR: bool
 711        - **Allow Depositary Receipts**:
 712            Companies with tickers ending in .Y and .F will be disallowed from trading within the
 713            model with this setting off. Turn it on to allow trading in these securities.
 714        - Constraints:
 715            Boolean value
 716        - Default Value: true
 717
 718    benchmark: array
 719        - **Benchmark**:
 720            Set one or more benchmarks and the weighting for each.
 721        - Constraints:
 722            Required.
 723            List of dicts with keys:
 724            gbi_id: integer representing the GBI ID of the benchmark index.
 725            weight: floating point value between 0 and 1.
 726            All gbi_id's in the dictionary must be unique, and the benchmark weights must sum to a
 727            number between 0 and 1.
 728        - Default Value: []
 729
 730    benchmarkAllocation: float
 731        - **Benchmark Allocation**:
 732            None
 733        - Constraints:
 734            Floating point value representing a percentage between -100 and 100
 735        - Default Value: 0
 736
 737    beta_neutral: bool
 738        - **Beta Neutral**:
 739            Adjust the weights to get the ex-ante Beta to be the net exposure of the portfolio. i.e.
 740            70% Long / 30% Short = 0.4 Beta"
 741        - Constraints:
 742            Boolean value
 743        - Default Value: false
 744
 745    bounds_method: str | null
 746        - **Optimizer Bounds**:
 747            Tight: The optimizer will only allow the weightings of securities in your portfolio to
 748            stay tight (close) to their initial weighting.
 749            Loose: The optimizer will allow the weightings of securities in your portfolio to move a
 750            medium amount more from their initial weighting.
 751            Wide: The optimizer will allow almost any weight between the minimum and maximum weight
 752            per long or short position.
 753        - Constraints:
 754            String enum of {loose, tight, wide}, or null
 755        - Default Value: null
 756
 757    compounding: bool
 758        - **Compound Returns**:
 759            When toggled on, this will allow the portfolio to compound returns.
 760        - Constraints:
 761            Boolean value
 762        - Default Value: true
 763
 764    currency: str
 765        - **Currency**:
 766            The currency you would like your portfolio to be calculated in. Note that if the
 767            currency differs from its exchange (i.e. GBP on the S&P), the prior close foreign
 768            exchange rate will be used for calculations.
 769        - Constraints:
 770            String representing a 3 digit ISO currency code.
 771        - Default Value: "USD"
 772
 773    equalWeightBenchmark: bool
 774        - **Equal Weight Benchmark**:
 775            Instead of using the defined benchmarks, set the benchmark to be an equal weighted (per
 776            rebalance period) version of the stock universe.
 777        - Constraints:
 778            Boolean value
 779        - Default Value: false
 780
 781    executionDelay: int
 782        - **Execution Delay**:
 783            This option adds the number of days selected to the trade execution. If you select T+1
 784            and your rebalance period is set to Weekly (Monday), it will trade on Tuesday, and so
 785            on.
 786        - Constraints:
 787            Integer value between 0 and 100, inclusive.
 788        - Default Value: 0
 789
 790    factorNeutralizeSignal: bool
 791        - **Signal Optimizer**:
 792            Turn on optimization at the signal level that will adjust signals and rankings according
 793            to the specifications you set. This is done prior to portfolio construction and can help
 794            reduce bias in the model.
 795        - Constraints:
 796            Boolean value
 797        - Default Value: false
 798
 799    investmentHorizon: int
 800        - **Investment Horizon**:
 801            The investment horizon for the portfolio.
 802        - Constraints:
 803            An integer representing a number of days
 804        - Default Value: 21
 805
 806    lower_turnover: bool
 807        - **Lower Turnover**:
 808            If toggled on the optimizer will try to solve the secondary goal of optimizing the
 809            primary goals while limiting turnover.
 810        - Constraints:
 811            Boolean value
 812        - Default Value: false
 813
 814    marketCapBounds: float
 815        - **Maximum Market Cap Variation**:
 816            How far from the target market cap weighted index each stock can deviate (positive or
 817            negative).
 818        - Constraints:
 819            Floating point value representing a percentage between 0 and 10
 820        - Default Value: 1
 821
 822    marketCapConstraint: bool
 823        - **Constrain Market Cap**:
 824            Force weighting to be near the target weights for a market cap weighted index of your
 825            entire stock universe.
 826        - Constraints:
 827            Boolean value
 828        - Default Value: false
 829
 830    marketCapFlex: float
 831        - **Market Cap Flex**:
 832            How far from the target market cap weighted the stock can deviate relative to the
 833            existing weight (i.e. at 75% a 1% position cannot exceed 1.75%).
 834        - Constraints:
 835            Floating point value representing a percentage between 10 and 200
 836        - Default Value: 100
 837
 838    maxLongPosition: float
 839        - **Max Long Position per Stock**:
 840            The maximum weighting of a long position within the portfolio.
 841        - Constraints:
 842            Required. Floating point value representing a percentage between 0.0 and 300.0
 843        - Default Value: 10.0
 844
 845    maxNumStockLong: int
 846        - **Maximum Number of Longs**:
 847            The maximum number of stocks to buy. This is on a per “portfolio” basis, so if you have
 848            sector neutral turned on it will be maximum per sector.
 849        - Constraints:
 850            Integer value between 0 and 1000, inclusive. Must be >= minNumStockLong
 851        - Default Value: 50
 852
 853    maxNumStockShort: int
 854        - **Maximum Number of Shorts**:
 855            The maximum number of stocks to short. This is on a per “portfolio” basis, so if you
 856            have sector neutral turned on it will be maximum per sector.
 857        - Constraints:
 858            Integer value between 0 and 1000, inclusive. Must be >= minNumStockShort
 859        - Default Value: 50
 860
 861    maxOwnership: float
 862        - **Maximum Ownership**:
 863            The maximum percentage of a company the portfolio is allowed to own. For example, if a
 864            company had a market cap of $100MM and this was 5% the portfolio could not own more than
 865            $5MM of that company.
 866        - Constraints:
 867            Floating point value representing a percentage between 0 and 100
 868        - Default Value: 5
 869
 870    maxShortPosition: float
 871        - **Max Short Position per Stock**:
 872            The maximum weighting of a short position within the portfolio.
 873        - Constraints:
 874            Required. Floating point value representing a percentage between 0.0 and 300.0
 875        - Default Value: 5.0
 876
 877    minimumSharePrice: float
 878        - **Minimum Share Price**:
 879            The minimum share price you want the portfolio to allow.
 880        - Constraints:
 881            Floating point value between 0 and 100000
 882        - Default Value: 2
 883
 884    minLongPosition: float
 885        - **Min Long Position per Stock**:
 886            The minimum weighting of a long position within the portfolio.
 887        - Constraints:
 888            Floating point value representing a percentage between 0.0 and 300.0
 889        - Default Value: 0
 890
 891    minNumStockLong: int
 892        - **Minimum Number of Longs**:
 893            The minimum number of stocks to buy. This is on a per “portfolio” basis, so if you have
 894            sector neutral turned on it will be minimum per sector.
 895        - Constraints:
 896            Integer value between 0 and 1000, inclusive. Must be <= maxNumStockLong
 897        - Default Value: 5
 898
 899    minNumStockShort: int
 900        - **Minimum Number of Shorts**:
 901            The minimum number of stocks to short. This is on a per “portfolio” basis, so if you
 902            have sector neutral turned on it will be minimum per sector.
 903        - Constraints:
 904            Integer value between 0 and 1000, inclusive. Must be <= maxNumStockShort
 905        - Default Value: 5
 906
 907    minShortPosition: float
 908        - **Min Short Position per Stock**:
 909            The minimum weighting of a short position within the portfolio.
 910        - Constraints:
 911            Floating point value representing a percentage between 0.0 and 100.0
 912        - Default Value: 0
 913
 914    missingMarketCap: float
 915        - **Missing Market Cap**:
 916            The amount in millions (MM) to replace any missing market capitalization information
 917            with. This will impact the maximum ownership setting.
 918        - Constraints:
 919            Floating point value between 0 and 100
 920        - Default Value: 10
 921
 922    nameBasedSectorWeighting: bool
 923        - **Name Based Sector Weighting**:
 924            Base sector weightings on number of names. For example, if there are 200 names in the
 925            index and financials has 20 companies, the weight of financials should be 10% (20/200).
 926        - Constraints:
 927            Boolean value
 928        - Default Value: false
 929
 930    netBenchmark: bool
 931        - **Adjust Benchmark for Net Exposure**:
 932            If your portfolio has a net exposure greater or less than 100%, this will adjust the
 933            benchmark returns to match that net exposure.
 934        - Constraints:
 935            Boolean value
 936        - Default Value: false
 937
 938    optimizer: str
 939        - **Optimizer Type**:
 940            No Optimization: None
 941            Reduce Risk: Optimizer designed to reduce portfolio volatility. This tends to result in
 942            the best overall performance.
 943            Maximize Sharpe: Optimizer designed to maximize Sharpe using out of sample estimates for
 944            expected return. Estimates for expected return have an outsized impact on the
 945            performance of this optimizer.
 946            Maximize Alpha: Optimizer designed to maximize expected return based on out-of-sample
 947            estimates for expected return. Estimates for expected return have an outsized impact on
 948            the performance of this optimizer.
 949            Min VaR: Minimize Value at Risk by looking back at the proposed portfolio over the last
 950            year and trying to minimize drawdowns.
 951            Max VaR Sharpe: Maximize Value at Risk Sharpe by looking back at the proposed portfolio
 952            over the last year and trying to maximize Sharpe by observed return for the portfolio vs
 953            observed volatility.
 954            Minimize Skew: Minimize the skew of the portfolio by trying to find a set of portfolio
 955            weightings that results in returns that are closer to the mean.
 956        - Constraints:
 957            Required. String enum: one of
 958            default: No Optimization
 959            min_vol: Reduce Risk
 960            max_sharpe: Maximize Sharpe
 961            max_alpha: Maximize Alpha
 962            min_var: Min VaR
 963            max_var_sharpe: Max VaR Sharpe
 964            min_skew: Minimize Skew
 965        - Default Value: "default"
 966
 967    optimizeTurnover: bool
 968        - **Turnover Optimization**:
 969            Turnover optimization will reduce the turnover at the signal level, making that ranked
 970            list more stable.
 971        - Constraints:
 972            Boolean value
 973        - Default Value: false
 974
 975    pairsTrading: bool
 976        - **Pairs Trading**:
 977            Pairs Trading forces the portfolio to be created by going long / short an equal number
 978            of stocks. The portfolio will try to find an offsetting position for every long by
 979            finding securities that are both highly correlated and have a significant difference in
 980            star rating.
 981        - Constraints:
 982            Boolean value
 983        - Default Value: false
 984
 985    percentPortfolioLong: float
 986        - **Percent of Portfolio Long**:
 987            The exact sum of all long position weightings in the portfolio.
 988        - Constraints:
 989            Required. Floating point value representing a percentage between 0.0 and 300.0
 990        - Default Value: 100.0
 991
 992    percentPortfolioShort: float
 993        - **Percent of Portfolio Short**:
 994            The exact sum of all short position weightings in the portfolio.
 995        - Constraints:
 996            Required. Floating point value representing a percentage between 0.0 and 300.0
 997        - Default Value: 0.0
 998
 999    percentToLong: float
1000        - **Percent to Long**:
1001            The machine will attempt to buy the top X% of stocks, subject to the minimum and maximum
1002            specified. This is on a per “portfolio” basis, so if you have sector neutral turned on
1003            it will be top X% per sector. This will be subject to the maximum and minimum number of
1004            securities you specify below.
1005        - Constraints:
1006            Floating point value representing a percentage between 0 and 100
1007        - Default Value: 20.0
1008
1009    percentToShort: float
1010        - **Percent to Short**:
1011            The machine will attempt to short the bottom X% of stocks, subject to the minimum and
1012            maximum specified. This is on a per “portfolio” basis, so if you have sector neutral
1013            turned on it will be bottom X% per sector. This will be subject to the maximum and
1014            minimum number of securities you specify below.
1015        - Constraints:
1016            Floating point value representing a percentage between 0 and 100
1017        - Default Value: 20.0
1018
1019    portfolioStartingValue: float
1020        - **Portfolio Starting Value**:
1021            The value of the portfolio in MM when it begins trading. If its backtest spans from 2005
1022            - 2020, the starting value in 2005 will be whatever you set here.
1023        - Constraints:
1024            Floating point value between 0 and 100000.
1025        - Default Value: 100.0
1026
1027    priceCleaning: bool
1028        - **Price Cleaning**:
1029            Price Cleaning removes any very large price movements from the securities, specifically
1030            with a daily change greater than +500% or -83.33%. There are some legitimate securities
1031            with moves this large that will be impacted by turning this on, but the advantage is it
1032            prevents these securities from overwhelming the backtest.
1033        - Constraints:
1034            Boolean value
1035        - Default Value: true
1036
1037    priceType: str
1038        - **Price Type**:
1039            None
1040        - Constraints:
1041            Required. String enum of {CLOSE, OPEN, VWAP}
1042        - Default Value: "VWAP"
1043
1044    rebalancePeriod: str
1045        - **Rebalance Period**:
1046            When the machine rebalances the portfolio. You can choose a specific day if you prefer
1047            to execute trades on a specific day.
1048        - Constraints:
1049            Required.
1050            An enum value in the following list:
1051            "daily"
1052            "weekly": Rebalances on every Monday.
1053            Chooses the next available trade date to rebalance when Monday is a holiday
1054            "weekly_wednesday": Rebalances on every Wednesday.
1055            Chooses the next available trade date to rebalance when Wednesday is a holiday
1056            "weekly_friday": Rebalances on every Friday.
1057            Chooses the previous available trade date to rebalance when Friday is a holiday
1058            "monthly"
1059            "quarterly"
1060            OR a string in the following format: "custom_x" where x is an integer between 1 and 252
1061            (days).
1062        - Default Value: "weekly"
1063
1064    sectorNeutral: bool
1065        - **Sector Neutral**:
1066            Will be constructed as a series of portfolios - each matching the market cap weighting
1067            of each of the stock universe sectors. This means that min. and max. number of stocks
1068            "per portfolio" becomes "per sector".
1069        - Constraints:
1070            Boolean value
1071        - Default Value: false
1072
1073    sectorNeutralEqualWeightBenchmark: bool
1074        - **Sector Neutral Equal Weight Benchmark**:
1075            Instead of using the defined benchmarks, set the benchmark to be a "sector neutral"
1076            equal weighted (per rebalance period) version of the stock universe. This takes the
1077            sector weighting and divides by the number of stocks in that sector, so each sector will
1078            have a different individual security weighting.
1079        - Constraints:
1080            Boolean value
1081        - Default Value: false
1082
1083    sectorNeutralSpread: float
1084        - **Sector Neutral Spread**:
1085            The sector neutral spread is how far away from the benchmark sector allocation the
1086            machine can deviate. This is adjusted for net exposure, i.e. if your net exposure is 0%
1087            the target sector allocations will be 0%.
1088        - Constraints:
1089            Floating point value representing a percentage between 0 and 100
1090        - Default Value: 0
1091
1092    signalIndustryNeutral: bool
1093        - **Industry Neutral**:
1094            Make the signal industry neutral, plus or minus the signal sector neutral spread.
1095        - Constraints:
1096            Boolean value
1097        - Default Value: false
1098
1099    signalSectorNeutral: bool
1100        - **Sector Neutral**:
1101            Make the signal sector neutral, plus or minus the signal sector neutral spread.
1102        - Constraints:
1103            Boolean value
1104        - Default Value: false
1105
1106    signalSectorNeutralSpread: float
1107        - **Sector Neutral Spread**:
1108            Make the signal sector neutral, plus or minus the signal sector neutral spread.
1109        - Constraints:
1110            Floating point value representing a percentage between 0 and 100
1111        - Default Value: 1.0
1112
1113    smoothPeriods: int
1114        - **Smooth Periods**:
1115            The number of periods over which to smooth the signals
1116        - Constraints:
1117            Integer value between 1 and 100.
1118        - Default Value: 1
1119
1120    smoothWeighting: str
1121        - **Smooth Weighting Type**:
1122            Alpha Weight: The strength of the signal matters in the smoothing. For example, if a
1123            stock had a score of 5 stars in period A, 2 stars in period B, your 2 period smoothing
1124            would be 7 / 2 = 3.5.
1125            Equal Weight: Only the direction of the signal matters here. For example, if you were 5
1126            stars in period A and 2 stars in period B, your 2 period smoothing would be 0 / 2 = 0
1127            (+1 in period 1 and -1 in period 2)
1128        - Constraints:
1129            One of {alpha_weight, equal_weight}
1130        - Default Value: "alpha_weight"
1131
1132    stopGain: bool
1133        - **Enable Stop Gain**:
1134            Turn on stop gains for the portfolio. This forces sales of securities that have exceeded
1135            the stop gain level. All trades will occur at the next trading time (i.e. next day OPEN
1136            for OPEN price models).
1137        - Constraints:
1138            Boolean value
1139        - Default Value: false
1140
1141    stopGainAmount: float
1142        - **Stop Gain Percentage to Sell**:
1143            The percentage of the position the machine will sell if the stop gain is triggered.
1144        - Constraints:
1145            Floating point value representing a percentage between 1 and 100.
1146        - Default Value: 50.0
1147
1148    stopGainLevel: float
1149        - **Stop Gain Threshold**:
1150            Will sell positions after they hit a threshold. For example, 10% / stop gain, when a
1151            position gains 10% the machine will sell a portion of the position (defined by stop gain
1152            percentage).
1153        - Constraints:
1154            Floating point value representing a percentage between 1 and 100.
1155        - Default Value: 10.0
1156
1157    stopLoss: bool
1158        - **Enable Stop Loss**:
1159            Turn on stop losses for the portfolio. This forces sales of securities that have
1160            exceeded the stop loss level. All trades will occur at the next trading time (i.e. next
1161            day OPEN for OPEN price models).
1162        - Constraints:
1163            Boolean value
1164        - Default Value: false
1165
1166    stopLossAmount: float
1167        - **Stop Loss Percentage to Sell**:
1168            The percentage of the position the machine will sell if the stop loss is triggered.
1169        - Constraints:
1170            Floating point value representing a percentage between 1 and 100.
1171        - Default Value: 50.0
1172
1173    stopLossLevel: float
1174        - **Stop Loss Threshold**:
1175            Will sell positions after they hit a threshold. For example, 10% / stop loss, when a
1176            position loses 10% the machine will sell a portion of the position (defined by stop loss
1177            percentage).
1178        - Constraints:
1179            Floating point value representing a percentage between 1 and 100.
1180        - Default Value: 10.0
1181
1182    stopLossReset: bool
1183        - **Allow multiple stop loss/gain between rebalance days**:
1184            Allows the machine to repeatedly trigger stop losses within a rebalance period. For
1185            example, if you trade Mondays and the stock drops 15% per day during the week and the
1186            stop loss trigger is 10%, then every day will trigger the stop loss. If toggled off the
1187            stop loss can only be triggered once per stock per rebalance period.
1188        - Constraints:
1189            Boolean value
1190        - Default Value: false
1191
1192    trackingConstraint: float
1193        - **Maximum Tracking Error (vs Benchmark)**:
1194            Amount of ex-ante tracking error to constrain the optimizer by.
1195        - Constraints:
1196            Floating point value representing a percentage between 0 and 30
1197        - Default Value: 10
1198
1199    trackingError: bool
1200        - **Allocate Weight to Benchmark**:
1201            Allocate a portion (%) of portfolio to the benchmark
1202        - Constraints:
1203            Boolean value
1204        - Default Value: false
1205
1206    trackingErrorOptimizer: bool
1207        - **Tracking Error**:
1208            If toggled on the optimizer will try to solve for an expected tracking error less than
1209            the amount specified. This is done out-of-sample and the ex post tracking error will
1210            likely be higher.
1211        - Constraints:
1212            Boolean value
1213        - Default Value: false
1214
1215    tradingCost: float
1216        - **Trading Cost**:
1217            A cost that will be applied to every trade.
1218        - Constraints:
1219            Required. Floating point value representing a percentage between 0.0 and 5.0
1220        - Default Value: 0.01
1221
1222    turnoverImportance: float
1223        - **Turnover Importance**:
1224            High importance means the algorithm will aim to keep turnover low, whereas low
1225            importance of turnover will let it vary more.
1226        - Constraints:
1227            Floating point value between 0.2 and 5 nonlinearly mapped onto the 1-9 interval.
1228        - Default Value: 1
1229
1230    useHoldingPeriod: bool
1231        - **Use Holding Period**:
1232            Set any covariance or other calculations within the optimizer to use a holding period
1233            return instead of daily return series
1234        - Constraints:
1235            Boolean value
1236        - Default Value: false
1237
1238    weightingType: str
1239        - **Initial Weighting**:
1240            Alpha Weight: The initial weighting will be done such that higher ranked stocks have a
1241            higher weight.
1242            Equal Weight: The initial weighting will be done such that all stocks selected to be in
1243            the portfolio will have an equal weight.
1244            Market Cap Weight: The initial weighting will be done such that all stocks are weighted
1245            according to their previous day’s market capitalization.
1246        - Constraints:
1247            One of {alpha_weight, equal_weight, market_cap_weight}
1248        - Default Value: "alpha_weight"
1249    """
1250
1251    # note, this is just the collection of portfolio settings
1252    # that is exposed to the API:
1253    # SELECT key, default_value
1254    # FROM portfolio_settings_validation
1255    # WHERE exposed_to_client_api;
1256    # TODO: expand to entire settings? why this way initially?
1257    __default_settings = json.loads(
1258        """{
1259      "adv": {
1260        "max": 25,
1261        "min": 0,
1262        "active": false,
1263        "method": "average",
1264        "num_days": 21,
1265        "daily_max": 100
1266      },
1267      "region": [
1268        "USA",
1269        "CAN"
1270      ],
1271      "allowDR": true,
1272      "lotSize": 1,
1273      "currency": "USD",
1274      "stopGain": false,
1275      "stopLoss": false,
1276      "twapDays": 1,
1277      "advFilter": {
1278        "active": false,
1279        "method": "average",
1280        "num_days": 21
1281      },
1282      "benchmark": [],
1283      "blacklist": "none",
1284      "closeEval": true,
1285      "hypermode": 0,
1286      "optimizer": "default",
1287      "priceType": "VWAP",
1288      "activeRisk": false,
1289      "enableTWAP": false,
1290      "mcapFilter": {
1291        "max": 10000,
1292        "min": 100,
1293        "active": false,
1294        "num_days": 21
1295      },
1296      "shortModel": "",
1297      "compounding": true,
1298      "fullOverlay": false,
1299      "model_style": "default",
1300      "recommender": {
1301        "active": false,
1302        "targetPortfolio": "",
1303        "investmentHorizon": "1M",
1304        "allocationMethodology": "recommenderPV"
1305      },
1306      "totalReturn": true,
1307      "tradingCost": 0.01,
1308      "beta_neutral": false,
1309      "combineModel": [],
1310      "denseSignals": {
1311        "addFwdVol": false,
1312        "addRicCode": false,
1313        "addFwdReturns": false,
1314        "addShareCounts": false
1315      },
1316      "macroTrading": {
1317        "active": false,
1318        "daysAbove": 5,
1319        "movingAverageDays": 50,
1320        "portfolioReduction": 30
1321      },
1322      "masterRegion": "NA",
1323      "maxOwnership": 5,
1324      "netBenchmark": false,
1325      "paParameters": {
1326        "data_type": "rank_all"
1327      },
1328      "pairsTrading": false,
1329      "targetEquity": {
1330        "active": false,
1331        "targetDates": []
1332      },
1333      "volTargeting": {
1334        "lb": 5,
1335        "ub": 20,
1336        "active": false
1337      },
1338      "basketTrading": {
1339        "active": false,
1340        "lookback": 252,
1341        "esgWeight": 1,
1342        "optimizer": "min_var",
1343        "betaWeight": 1,
1344        "dataWeight": 1,
1345        "correlation": false,
1346        "equalWeight": true,
1347        "hedgeMethod": "simple",
1348        "hedgeStocks": [],
1349        "longPrimary": true,
1350        "priceWeight": 1,
1351        "factorWeight": 1,
1352        "primaryStocks": [],
1353        "hedgePortfolio": false,
1354        "numHedgeStocks": 20,
1355        "factorTargeting": false,
1356        "maxPositionSize": 0,
1357        "minPositionSize": 0,
1358        "optimizerWeight": 75,
1359        "secondaryStocks": [],
1360        "secondaryWeight": 0,
1361        "worstPercentage": 50,
1362        "numPrimaryStocks": 10,
1363        "restrictedStocks": [],
1364        "signalImportance": 1,
1365        "factorsAndTargets": [],
1366        "numSecondaryStocks": 10,
1367        "positionSizeBounds": "",
1368        "turnoverImportance": 1,
1369        "secondaryBasketType": "hedge",
1370        "hedgePortfolioPicker": [],
1371        "portfolioPointInTime": false
1372      },
1373      "bounds_method": null,
1374      "combineMethod": "overlay",
1375      "explain_model": {
1376        "active": false,
1377        "method": "winsorize",
1378        "threshold": 3
1379      },
1380      "factorFilters": [],
1381      "indexMatching": {
1382        "active": false,
1383        "numStocksToIndex": 1,
1384        "highestRankAllowed": 3
1385      },
1386      "marketCapFlex": 100,
1387      "percentToLong": 20,
1388      "priceCleaning": true,
1389      "rebalanceDays": [
1390        true,
1391        true,
1392        true,
1393        true,
1394        true
1395      ],
1396      "regionNeutral": false,
1397      "sectorNeutral": false,
1398      "sectorWeights": {},
1399      "smoothPeriods": 1,
1400      "stopGainLevel": 10,
1401      "stopLossLevel": 10,
1402      "stopLossReset": false,
1403      "trackingError": false,
1404      "triggerEvents": {
1405        "active": false
1406      },
1407      "weightingType": "equal_weight",
1408      "executionDelay": 0,
1409      "insertUniverse": null,
1410      "lower_turnover": false,
1411      "mlModelFactors": {
1412        "max": 10,
1413        "active": false
1414      },
1415      "percentToShort": 5,
1416      "stopGainAmount": 50,
1417      "stopLossAmount": 50,
1418      "backtestEndDate": "2050-01-01",
1419      "benchmarkAdjust": 2,
1420      "coreModelWeight": 33.34,
1421      "longBufferLimit": 50,
1422      "marketCapBounds": 1,
1423      "maxLongPosition": 10,
1424      "maxNumStockLong": 100,
1425      "minLongPosition": 0,
1426      "minNumStockLong": 20,
1427      "rebalancePeriod": "weekly_monday",
1428      "smoothWeighting": "alpha_weight",
1429      "taxOptimization": {
1430        "active": false,
1431        "num_days": 30,
1432        "taxThreshold": 20,
1433        "useSectorETFs": false,
1434        "readjustToCore": false
1435      },
1436      "tradingSettings": {
1437        "borrowRate": 0.5,
1438        "useBorrowRateData": true,
1439        "forceRebalanceDates": []
1440      },
1441      "factorTradeRules": [],
1442      "heuristicTrading": false,
1443      "holidayTolerance": 0,
1444      "includeDividends": true,
1445      "isDirectIndexing": false,
1446      "macroTradingLong": {
1447        "active": false,
1448        "daysAbove": 5,
1449        "movingAverageDays": 50,
1450        "portfolioReduction": 30
1451      },
1452      "maxNumStockShort": 200,
1453      "maxSectorWeights": {},
1454      "maxShortPosition": 1,
1455      "maximumOwnership": 100,
1456      "minNumStockShort": 20,
1457      "minShortPosition": 0,
1458      "missingMarketCap": 10,
1459      "optimizeTurnover": false,
1460      "percentileFilter": false,
1461      "shortBufferLimit": 50,
1462      "stopLossGainLong": {
1463        "stopGain": false,
1464        "stopLoss": false,
1465        "stopGainLevel": 10,
1466        "stopLossLevel": 10,
1467        "stopGainAmount": 50,
1468        "stopLossAmount": 50
1469      },
1470      "useHoldingPeriod": false,
1471      "backtestStartDate": "2008-01-01",
1472      "benchmarkOperator": "addition",
1473      "benchmarkSettings": {
1474        "convertSignalsToMarketCap": false
1475      },
1476      "combinePortfolios": [],
1477      "factorConstraints": [],
1478      "investmentHorizon": 21,
1479      "longTermTimeFrame": 63,
1480      "macroTradingShort": {
1481        "active": false,
1482        "daysAbove": 5,
1483        "movingAverageDays": 50,
1484        "portfolioReduction": 30
1485      },
1486      "minimumSharePrice": 2,
1487      "proportionateRisk": false,
1488      "recalcRequestTime": "2024-04-02T19:14:59.145Z",
1489      "selectedBenchmark": 10076,
1490      "stopLossGainShort": {
1491        "stopGain": false,
1492        "stopLoss": false,
1493        "stopGainLevel": 10,
1494        "stopLossLevel": 10,
1495        "stopGainAmount": 50,
1496        "stopLossAmount": 50
1497      },
1498      "turnoverBuffering": false,
1499      "benchmarkPortfolio": false,
1500      "factorSegmentation": {
1501        "active": false,
1502        "factorSlices": 10,
1503        "targetFactor": "size"
1504      },
1505      "ignore_constraints": false,
1506      "longTermImportance": 0,
1507      "reduceMinorTrading": {
1508        "min": 1,
1509        "active": false
1510      },
1511      "shortTermTimeFrame": 5,
1512      "signalsByMarketCap": {
1513        "active": false
1514      },
1515      "trackingConstraint": 10,
1516      "turnoverImportance": 5,
1517      "benchmarkAllocation": 0,
1518      "defineRegionWeights": {
1519        "active": false,
1520        "default": null,
1521        "weights": {}
1522      },
1523      "defineSectorWeights": false,
1524      "longBufferNumStocks": 5,
1525      "marketCapConstraint": false,
1526      "mcapWeightBenchmark": false,
1527      "mediumTermTimeFrame": 21,
1528      "regionNeutralSpread": 2,
1529      "sectorNeutralSpread": 3,
1530      "shortTermImportance": 0,
1531      "signalOptimizerType": "max_alpha",
1532      "signalSectorNeutral": false,
1533      "customRebalanceDates": [],
1534      "equalWeightBenchmark": true,
1535      "insertUniverseToggle": false,
1536      "maxStockForPortfolio": 200,
1537      "mediumTermImportance": 50,
1538      "minStockForPortfolio": 5,
1539      "percentPortfolioLong": 100,
1540      "reportingStockFilter": {
1541        "days": 10,
1542        "active": false
1543      },
1544      "secondaryConstraints": [],
1545      "shortBufferNumStocks": 5,
1546      "originalSignalWeights": false,
1547      "percentPortfolioShort": 0,
1548      "signalIndustryNeutral": false,
1549      "allowCompanyCollisions": true,
1550      "defineMaxSectorWeights": false,
1551      "dividendYieldOptimizer": false,
1552      "factorNeutralizeSignal": false,
1553      "portfolioStartingValue": 100,
1554      "trackingErrorOptimizer": false,
1555      "signalFactorConstraints": [
1556        {
1557          "lb": -0.25,
1558          "ub": 0.25,
1559          "factor": "machine_1"
1560        },
1561        {
1562          "lb": -0.25,
1563          "ub": 0.25,
1564          "factor": "machine_2"
1565        },
1566        {
1567          "lb": -0.25,
1568          "ub": 0.25,
1569          "factor": "machine_3"
1570        },
1571        {
1572          "lb": -0.25,
1573          "ub": 0.25,
1574          "factor": "machine_4"
1575        },
1576        {
1577          "lb": -0.25,
1578          "ub": 0.25,
1579          "factor": "machine_5"
1580        },
1581        {
1582          "lb": -0.25,
1583          "ub": 0.25,
1584          "factor": "machine_6"
1585        },
1586        {
1587          "lb": -0.25,
1588          "ub": 0.25,
1589          "factor": "machine_7"
1590        },
1591        {
1592          "lb": -0.25,
1593          "ub": 0.25,
1594          "factor": "machine_8"
1595        },
1596        {
1597          "lb": -0.25,
1598          "ub": 0.25,
1599          "factor": "machine_9"
1600        },
1601        {
1602          "lb": -0.25,
1603          "ub": 0.25,
1604          "factor": "machine_10"
1605        }
1606      ],
1607      "signalProportionateRisk": false,
1608      "topBottomPercentToTrade": 20,
1609      "useCustomRebalanceDates": false,
1610      "nameBasedSectorWeighting": false,
1611      "percentileFilterBySector": false,
1612      "tradeByPercentOfRankings": false,
1613      "signalSectorNeutralSpread": 1,
1614      "pairsTradingMinCorrelation": 0.5,
1615      "removeBlacklistFromRankings": false,
1616      "stopLossGainSameDayExecution": true,
1617      "excess_return_relative_to_beta": true,
1618      "sectorNeutralEqualWeightBenchmark": false,
1619      "industryNeutralEqualWeightBenchmark": false
1620    }"""
1621    )
1622
1623    def __init__(self, settings: Optional[Dict] = None):
1624        # TODO: i'd rather have kwargs for the different keys and then allow
1625        # for per-key overrides, but we start with this more conservative approach
1626        if settings is None:
1627            self.settings = copy.deepcopy(PortfolioSettings.__default_settings)
1628        else:
1629            self.settings = settings
1630
1631    def toDict(self):
1632        return self.settings
1633
1634    def __str__(self):
1635        return json.dumps(self.settings)
1636
1637    def __repr__(self):
1638        return self.__str__()
1639
1640    def fromDict(settings):
1641        return PortfolioSettings(settings)
1642
1643
1644hedge_experiment_type = Literal["HEDGE", "MIMIC"]
1645
1646
1647@dataclass(frozen=True)  # from _python client's_ perspective, instances will never change!
1648class HedgeExperiment:
1649    id: str  # really a uuid, which we represent as a string
1650    name: str
1651    user_id: str  # see id comment
1652    description: str
1653    experiment_type: hedge_experiment_type  # TODO: enum worth it?
1654    last_calculated: dt.datetime
1655    last_modified: dt.datetime
1656    status: str  # TODO: enum worth it?
1657    portfolio_calculation_status: str  # TODO: enum worth it?
1658    selected_models: List[str]  # see id comment
1659    target_securities: Dict[GbiIdSecurity, float]  # Security is a hashable type because frozen=True
1660    target_portfolios: List[str]
1661    selected_stock_universe_ids: List[str]  # see id comment
1662    baseline_model: Optional[str] = None
1663    baseline_stock_universe_id: Optional[str] = None
1664    baseline_scenario: Optional["HedgeExperimentScenario"] = None
1665
1666    @property
1667    def config(self) -> Dict:
1668        """
1669        Returns a hedge experiment configuration dictionary, ready for JSON-serialization and
1670        submission.
1671        """
1672        weights_by_gbiid = [
1673            {"gbiId": sec.id, "weight": weight} for sec, weight in self.target_securities.items()
1674        ]
1675        return {
1676            "experimentType": self.experiment_type,
1677            "selectedModels": self.selected_models,
1678            "targetSecurities": weights_by_gbiid,
1679            "selectedStockUniverseIds": self._selected_stock_universe_ids,
1680        }
1681
1682    @classmethod
1683    def from_json_dict(cls, d: Dict) -> "HedgeExperiment":
1684        # drafts arent fully populated
1685        if d["status"] == "DRAFT":
1686            weights_by_security = {}
1687            selected_models = []
1688            selected_stock_universe_ids = []
1689        else:
1690            weights_by_security = {
1691                GbiIdSecurity(
1692                    sec_dict["gbiId"],
1693                    None,
1694                    sec_dict["security"]["symbol"],
1695                    sec_dict["security"]["name"],
1696                ): sec_dict["weight"]
1697                for sec_dict in d["targetSecurities"]
1698            }
1699            experiment_config = json.loads(d["config"])
1700            selected_models = experiment_config["selectedModels"]
1701            selected_stock_universe_ids = experiment_config["selectedStockUniverseIds"]
1702        baseline_scenario = None
1703        if d["baselineScenario"] is not None:
1704            baseline_scenario = HedgeExperimentScenario.from_json_dict(d["baselineScenario"])
1705        return cls(
1706            d["hedgeExperimentId"],
1707            d["experimentName"],
1708            d["userId"],
1709            d["description"],
1710            d["experimentType"],
1711            d["lastCalculated"],
1712            d["lastModified"],
1713            d["status"],
1714            d["portfolioCalcStatus"],
1715            selected_models,
1716            weights_by_security,
1717            d.get("targetPortfolios"),
1718            selected_stock_universe_ids or [],
1719            d.get("baselineModel"),
1720            d.get("baselineStockUniverseId"),
1721            baseline_scenario,
1722        )
1723
1724
1725@dataclass(frozen=True)
1726class HedgeExperimentScenario:
1727    id: str  # really a uuid, which we represent as a string;
1728    name: str
1729    description: str
1730    status: str  # TODO: enum worth it?
1731    settings: PortfolioSettings
1732    summary: pd.DataFrame
1733    # we currently a portfolios field. they get wrapped up into the summary table
1734
1735    @classmethod
1736    def from_json_dict(cls, d: Dict) -> "HedgeExperimentScenario":
1737        return cls(
1738            d["hedgeExperimentScenarioId"],
1739            d["scenarioName"],
1740            d["description"],
1741            d.get("status"),
1742            PortfolioSettings(json.loads(d["portfolioSettingsJson"])),
1743            HedgeExperimentScenario._build_portfolio_summary(d.get("hedgeExperimentPortfolios")),
1744        )
1745
1746    @staticmethod
1747    def _build_portfolio_summary(portfolios: Dict) -> pd.DataFrame:
1748        # this happens for added scenarios that havent run yet
1749        if portfolios is None:
1750            return pd.DataFrame()
1751
1752        df_dict = defaultdict(list)
1753        for pf in portfolios:
1754            p = pf["portfolio"]
1755
1756            df_dict["portfolio_id"].append(p["id"])
1757            df_dict["scenario_name"].append(p["name"])
1758            df_dict["model_id"].append(p["modelId"])
1759            df_dict["status"].append(p["status"])
1760
1761            if p["status"] != "READY":  # data isn't yet available
1762                df_dict["1M"].append(np.nan)
1763                df_dict["3M"].append(np.nan)
1764                df_dict["1Y"].append(np.nan)
1765                df_dict["sharpe"].append(np.nan)
1766                df_dict["vol"].append(np.nan)
1767            else:
1768                # NOTE:
1769                # these are the magic indices/keys of these values; inspect passed arg to see
1770                # if upstream changes the order of (sub-)elements in the response...uh oh
1771                # TODO: specific key search? wrap with try/except and fail loudly?
1772                df_dict["1M"].append(p["performanceGrid"][0][4])
1773                df_dict["3M"].append(p["performanceGrid"][0][5])
1774                df_dict["1Y"].append(p["performanceGrid"][0][7])
1775                df_dict["sharpe"].append(p["tearSheet"][0]["members"][1]["value"])
1776                pf_stddev = p["tearSheet"][1]["members"][1]["value"]
1777                bnchmk_stddev = p["tearSheet"][1]["members"][2]["value"]
1778                df_dict["vol"].append((pf_stddev - bnchmk_stddev) * 100)
1779                # TODO: this is how it is done on the front-end,
1780                # should be pulled out of both here and there
1781
1782        df = pd.DataFrame(df_dict)
1783        return df
1784
1785
1786@dataclass(frozen=True)  # from _python client's_ perspective, instances will never change!
1787class HedgeExperimentDetails:
1788    # this will probably lead to violations of the law of demeter, but it's easy to do right now,
1789    # particularly for an unproven API
1790    experiment: HedgeExperiment
1791    scenarios: Dict[str, HedgeExperimentScenario]
1792
1793    @property
1794    def summary(self) -> pd.DataFrame:
1795        """
1796        Returns a dataframe corresponding to the Hedge Experiment "flat view" - all portfolio
1797        options are displayed
1798        """
1799        if len(self.scenarios) == 0 or all(s.status != "READY" for s in self.scenarios.values()):
1800            return pd.DataFrame()
1801        return pd.concat(scenario.summary for scenario in self.scenarios.values()).sort_values(
1802            ["scenario_name"]
1803        )  # sort for stable presentation
1804
1805    @classmethod
1806    def from_json_dict(cls, d: Dict) -> "HedgeExperimentDetails":
1807        he = HedgeExperiment.from_json_dict(d)
1808        scenarios = {
1809            scenario_dict["hedgeExperimentScenarioId"]: HedgeExperimentScenario.from_json_dict(
1810                scenario_dict
1811            )
1812            for scenario_dict in d["hedgeExperimentScenarios"]
1813        }
1814        return cls(he, scenarios)