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
  56    def __str__(self):
  57        if self.name == "STOCK":
  58            return "STOCK"
  59        elif self.name == "GLOBAL":
  60            return "GLOBAL"
  61        elif self.name == "STRATEGY":
  62            return "STRATEGY"
  63        else:
  64            return "UNKNOWN"
  65
  66
  67class DataSetSubType(Enum):
  68    UNKNOWN = 0
  69    DENSE = 1
  70    SPARSE_HIST = 2
  71    SPARSE_FWD = 3
  72
  73    def __str__(self):
  74        if self.name == "DENSE":
  75            return "DENSE"
  76        elif self.name == "SPARSE_HIST":
  77            return "SPARSE_HIST"
  78        elif self.name == "SPARSE_FWD":
  79            return "SPARSE_FWD"
  80        else:
  81            return "UNKNOWN"
  82
  83
  84class DataSetFrequency(Enum):
  85    UNKNOWN = 0
  86    DAILY = 1
  87    WEEKLY = 2
  88    MONTHLY = 3
  89    QUARTERLY = 4
  90    SEMIANNUAL = 5
  91    ANNUAL = 6
  92
  93    def __str__(self):
  94        if self.name == "DAILY":
  95            return "DAILY"
  96        elif self.name == "WEEKLY":
  97            return "WEEKLY"
  98        elif self.name == "MONTHLY":
  99            return "MONTHLY"
 100        elif self.name == "QUARTERLY":
 101            return "QUARTERLY"
 102        elif self.name == "SEMIANNUAL":
 103            return "SEMIANNUAL"
 104        elif self.name == "ANNUAL":
 105            return "ANNUAL"
 106        else:
 107            return "UNKNOWN"
 108
 109
 110class ColumnRole(Enum):
 111    UNKNOWN = 0
 112    VARIABLE = 1
 113    GOAL = 2
 114    METRIC = 3
 115    IDENTIFIER = 4
 116
 117    def __str__(self):
 118        if self.name == "VARIABLE":
 119            return "VARIABLE"
 120        elif self.name == "GOAL":
 121            return "GOAL"
 122        elif self.name == "METRIC":
 123            return "METRIC"
 124        elif self.name == "IDENTIFIER":
 125            return "IDENTIFIER"
 126        else:
 127            return "UNKNOWN"
 128
 129
 130class ColumnSubRole(Enum):
 131    UNKNOWN = 0
 132    GBI_ID = 1
 133    ISIN = 2
 134    GVKEY = 3
 135    IID = 4
 136    SYMBOL = 5
 137    COUNTRY = 6
 138    CURRENCY = 7
 139    DATE = 8
 140    COMPANY_NAME = 9
 141    REPORT_DATE = 10
 142    REPORT_PERIOD = 11
 143
 144    def __str__(self):
 145        if self.name == "GBI_ID":
 146            return "GBI_ID"
 147        elif self.name == "ISIN":
 148            return "ISIN"
 149        elif self.name == "GVKEY":
 150            return "GVKEY"
 151        elif self.name == "IID":
 152            return "IID"
 153        elif self.name == "SYMBOL":
 154            return "SYMBOL"
 155        elif self.name == "COUNTRY":
 156            return "COUNTRY"
 157        elif self.name == "CURRENCY":
 158            return "CURRENCY"
 159        elif self.name == "DATE":
 160            return "DATE"
 161        elif self.name == "COMPANY_NAME":
 162            return "COMPANY_NAME"
 163        elif self.name == "REPORT_DATE":
 164            return "REPORT_DATE"
 165        elif self.name == "REPORT_PERIOD":
 166            return "REPORT_PERIOD"
 167        else:
 168            return "UNKNOWN"
 169
 170    def get_match(column_name):
 171        def clean_str(name):
 172            translation = str.maketrans("", "", string.punctuation)
 173            clean_name = name.strip().translate(translation).lower()
 174            return re.sub(r"\s+", "", clean_name)
 175
 176        identifiers = [
 177            ColumnSubRole.GBI_ID,
 178            ColumnSubRole.ISIN,
 179            ColumnSubRole.GVKEY,
 180            ColumnSubRole.IID,
 181            ColumnSubRole.SYMBOL,
 182            ColumnSubRole.COUNTRY,
 183            ColumnSubRole.CURRENCY,
 184            ColumnSubRole.COMPANY_NAME,
 185            ColumnSubRole.REPORT_DATE,
 186            ColumnSubRole.REPORT_PERIOD,
 187        ]
 188
 189        for identifier in identifiers:
 190            if clean_str(str(identifier)) == clean_str(column_name):
 191                return identifier
 192        return None
 193
 194
 195class ColumnValueType(Enum):
 196    UNKNOWN = 0
 197    NUMBER = 1
 198    STRING = 2
 199
 200    def __str__(self):
 201        if self.name == "UNKNOWN":
 202            return "UNKNOWN"
 203        elif self.name == "NUMBER":
 204            return "NUMBER"
 205        elif self.name == "STRING":
 206            return "STRING"
 207        else:
 208            return "UNKNOWN"
 209
 210
 211class ColumnConfig:
 212    def __init__(
 213        self,
 214        name=None,
 215        role=None,
 216        sub_role=None,
 217        value_type=ColumnValueType.NUMBER,
 218        description="",
 219        investment_horizon=None,
 220    ):
 221        self.name = name
 222        self.role = role
 223        self.sub_role = sub_role
 224        self.value_type = value_type
 225        # More value_types will be supported in the future.
 226        self.description = description
 227        self.investment_horizon = investment_horizon
 228
 229    def __str__(self):
 230        return 'Name: "{0}", Role: {1}, SubRole: {2}, Value type: {3}, Desc: {4} IH: {5}.'.format(
 231            self.name,
 232            self.role,
 233            self.sub_role,
 234            self.value_type,
 235            self.description,
 236            self.investment_horizon,
 237        )
 238
 239    def __repr__(self):
 240        return self.__str__()
 241
 242
 243class StrategyConfig:
 244    def __init__(self, name=None, source_name=None):
 245        self.name = name
 246        self.source_name = source_name
 247
 248    def __str__(self):
 249        return 'Name: "{0}", Source Name: {1}.'.format(self.name, self.source_name)
 250
 251    def __repr__(self):
 252        return self.__str__()
 253
 254
 255class BoostedDataSetSchemaException(Exception):
 256    def __init__(self, value, data=None):
 257        self.value = value
 258        self.data = data
 259
 260    def __str__(self):
 261        return repr(self.value)
 262
 263
 264class DataSetConfig:
 265    def __init__(
 266        self,
 267        name,
 268        datasetType=DataSetType.STOCK,
 269        datasetSubType=DataSetSubType.DENSE,
 270        datasetFrequency=DataSetFrequency.DAILY,
 271    ):
 272        self.name = name
 273        self.type = datasetType
 274        self.subtype = datasetSubType
 275        self.frequency = datasetFrequency
 276        self.columns = []
 277        self.strategies = []
 278
 279    def addColumn(self, columnConfig):
 280        self.columns.append(columnConfig)
 281
 282    def addStrategy(self, strategyConfig):
 283        self.strategies.append(strategyConfig)
 284
 285    def __getColumnByName(self, col_name):
 286        for column in self.columns:
 287            if col_name == column.name:
 288                return column
 289        raise BoostedDataSetSchemaException(f"Unable to find column {col_name}")
 290
 291    def updateColumnToGoal(self, col_name, investment_horizon):
 292        column = self.__getColumnByName(col_name)
 293        column.role = ColumnRole.GOAL
 294        column.investment_horizon = int(investment_horizon)
 295
 296    def updateColumnToMetric(self, col_name):
 297        column = self.__getColumnByName(col_name)
 298        column.role = ColumnRole.METRIC
 299
 300    def updateColumnToVariable(self, col_name):
 301        column = self.__getColumnByName(col_name)
 302        column.role = ColumnRole.VARIABLE
 303
 304    def __validateSchema(self):
 305        num_goals = 0
 306        num_metrics = 0
 307        dt = self.type
 308        dst = self.subtype
 309        dsf = self.frequency
 310        if len(self.columns) == 0:
 311            msg = "No feature columns exist."
 312            raise BoostedDataSetSchemaException(msg)
 313
 314        if dst in [DataSetSubType.SPARSE_HIST, DataSetSubType.SPARSE_FWD]:
 315            if dsf not in [DataSetFrequency.QUARTERLY]:
 316                msg = f"{dsf} frequency is not supported for {dst} sub data"
 317                raise BoostedDataSetSchemaException(msg)
 318            if dt not in [DataSetType.STOCK]:
 319                msg = f"{dst} subtype is not supported for {dt} data"
 320                raise BoostedDataSetSchemaException(msg)
 321
 322        for column in self.columns:
 323            if column.role == ColumnRole.GOAL:
 324                ih = column.investment_horizon
 325                gn = column.name
 326                if dt == DataSetType.GLOBAL:
 327                    msg = f"{dt} data can not have {ColumnRole.GOAL} type"
 328                    raise BoostedDataSetSchemaException(msg)
 329                if not isinstance(ih, int):
 330                    msg = f"Investment horizon for {gn} must be an integer"
 331                    raise BoostedDataSetSchemaException(msg)
 332                if ih < 1 or ih > 252:
 333                    msg = f"Investment horizon must be between 1 and 252 for {gn}"
 334                    raise BoostedDataSetSchemaException(msg)
 335                num_goals += 1
 336            elif column.role == ColumnRole.METRIC:
 337                if dt in [DataSetType.GLOBAL, DataSetType.STOCK]:
 338                    msg = f"{dt} data can not have {ColumnRole.METRIC} type"
 339                    raise BoostedDataSetSchemaException(msg)
 340                num_metrics += 1
 341
 342        if dt == DataSetType.STRATEGY:
 343            if num_goals == 0:
 344                msg = "Independent data requires at least one goal."
 345                raise BoostedDataSetSchemaException(msg)
 346            if num_metrics == 0:
 347                msg = "Independent data requires at least one metric."
 348                raise BoostedDataSetSchemaException(msg)
 349            if len(self.strategies) <= 1:
 350                msg = "Independent data requires more than 1 strategy"
 351                raise BoostedDataSetSchemaException(msg)
 352
 353    def toDict(self):
 354        self.__validateSchema()
 355        config = {}
 356        config["name"] = self.name
 357        config["type"] = str(self.type)
 358        config["subType"] = str(self.subtype)
 359        config["frequency"] = str(self.frequency)
 360        featureList = []
 361        for i, f in enumerate(self.columns):
 362            fm = {}
 363            fm["name"] = f.name
 364            fm["description"] = f.description
 365            fm["type"] = str(f.role)
 366            fm["role"] = str(f.role)
 367            fm["subRole"] = str(f.sub_role) if f.sub_role is not None else None
 368            fm["valuesType"] = str(f.value_type)
 369            fm["columnName"] = f.name
 370            fm["investmentHorizon"] = f.investment_horizon
 371            featureList.append(fm)
 372        config["features"] = featureList
 373        strategyList = []
 374        for i, s in enumerate(self.strategies):
 375            sm = {}
 376            sm["name"] = s.name
 377            sm["sourceName"] = s.source_name
 378            strategyList.append(sm)
 379        config["strategies"] = strategyList
 380        return config
 381
 382    def __str__(self):
 383        a = ""
 384        a += "Name: {0}\n".format(self.name)
 385        a += "Columns: \n"
 386        for c in self.columns:
 387            a += "  {0}\n".format(c)
 388        return a
 389
 390    def __repr__(self):
 391        return self.__str__()
 392
 393    def fromDict(schema):
 394        subtype = DataSetSubType[schema.get("subtype", str(DataSetSubType.DENSE))]
 395        frequency = DataSetFrequency[schema.get("frequency", str(DataSetFrequency.DAILY))]
 396        config = DataSetConfig(
 397            schema["name"],
 398            datasetType=DataSetType[schema["type"]],
 399            datasetSubType=subtype,
 400            datasetFrequency=frequency,
 401        )
 402        # two things left to fill in - strategies and columns
 403        for strategy_data in schema["strategies"]:
 404            config.addStrategy(
 405                StrategyConfig(name=strategy_data["name"], source_name=strategy_data["sourceName"])
 406            )
 407
 408        for feature_data in schema["features"]:
 409            config.addColumn(
 410                ColumnConfig(
 411                    name=feature_data["columnName"],
 412                    description=feature_data["description"] or "",
 413                    investment_horizon=feature_data["investmentHorizon"],
 414                    value_type=ColumnValueType[feature_data["valuesType"]]
 415                    if feature_data["valuesType"] is not None
 416                    else ColumnValueType.NUMBER,
 417                    role=ColumnRole[feature_data["role"]]
 418                    if feature_data["role"] is not None
 419                    else None,
 420                    sub_role=ColumnSubRole[feature_data["subRole"]]
 421                    if feature_data["subRole"] is not None
 422                    else None,
 423                )
 424            )
 425
 426        config.__validateSchema()
 427        return config
 428
 429
 430class GbiIdSecurityException(Exception):
 431    def __init__(self, value, data=None):
 432        self.value = value
 433        self.data = data
 434
 435    def __str__(self):
 436        return repr(self.value)
 437
 438
 439class GbiIdSecurity:
 440    def __init__(self, gbi_id, isin_country_currency_date, ticker, company_name):
 441        self.gbi_id = gbi_id
 442        self.isin_info = isin_country_currency_date
 443        self.ticker = ticker
 444        self.company_name = company_name
 445
 446    def __str__(self):
 447        return '\n(gbi_id: "{0}", isin_info: {1}, ticker: {2}, company_name: {3})'.format(
 448            self.gbi_id, self.isin_info.__str__(), self.ticker, self.company_name
 449        )
 450
 451    def __repr__(self):
 452        return self.__str__()
 453
 454    def __eq__(self, __o: object) -> bool:
 455        return self.gbi_id == __o.gbi_id
 456
 457    def __hash__(self):
 458        return hash(self.gbi_id)
 459
 460
 461class DateIdentCountryCurrencyException(Exception):
 462    def __init__(self, value, data=None):
 463        self.value = value
 464        self.data = data
 465
 466    def __str__(self):
 467        return repr(self.value)
 468
 469
 470# for backward compatibility
 471class DateIsinCountryCurrencyException(DateIdentCountryCurrencyException):
 472    pass
 473
 474
 475class DateIdentCountryCurrency:
 476    def __init__(
 477        self,
 478        date: str,
 479        identifier: str,
 480        country: Optional[str] = None,
 481        currency: Optional[str] = None,
 482        id_type: ColumnSubRole = ColumnSubRole.ISIN,
 483    ):
 484        self.date = date
 485        self.identifier = identifier
 486        self.id_type = id_type
 487        self.country = country
 488        self.currency = currency
 489        self.__validateInput()
 490
 491    def __str__(self):
 492        return '(date: "{0}", identifier: "{1}", country: {2}, currency: {3})'.format(
 493            self.date, self.identifier, self.country, self.currency
 494        )
 495
 496    def __repr__(self):
 497        return self.__str__()
 498
 499    def __validateInput(self):
 500        # simply ensure that at least isin and date are filled out.
 501        # country/currency defaults to ANY if not filled out, but
 502        # still is not recommended.
 503        if self.identifier is None or self.date is None:
 504            raise DateIdentCountryCurrencyException(
 505                "ISIN or Date not provided while constructing DateIsinCountryCurrency"
 506            )
 507
 508        if self.id_type not in (ColumnSubRole.ISIN, ColumnSubRole.SYMBOL):
 509            raise DateIdentCountryCurrencyException(f"Invalid ID Type: {self.id_type}")
 510
 511        def check_is_str(value, fieldname):
 512            if value is not None and not isinstance(value, str):
 513                raise DateIdentCountryCurrencyException(
 514                    f"Field {fieldname} in DateIsinCountryCurrency was not a string."
 515                )
 516
 517        check_is_str(self.date, "date")
 518        check_is_str(self.identifier, "identifier")
 519        check_is_str(self.country, "country")
 520        check_is_str(self.currency, "currency")
 521
 522
 523# for backwards compatibility
 524class DateIsinCountryCurrency(DateIdentCountryCurrency):
 525    def __init__(self, date, isin, country, currency):
 526        super().__init__(date, isin, country, currency, ColumnSubRole.ISIN)
 527        self.isin = isin
 528
 529    def __str__(self):
 530        return '(date: "{0}", isin: "{1}", country: {2}, currency: {3})'.format(
 531            self.date, self.isin, self.country, self.currency
 532        )
 533
 534
 535class IdentifierToColumnMapping:
 536    """
 537    IdentifierToColumnMapping is a mapping from string to boosted.api.api_type.ColumnSubRole.
 538    The key of the mapping corresponds to a CSV column name, and the value corresponds
 539    to the type of identifier that it maps to. Only columns specifying an identifying factor
 540    for the stock needs to be specified (e.g. ISIN, Date, Symbol, Currency)
 541    """
 542
 543    def __init__(self, mapping):
 544        self.mapping = mapping
 545        self.__validateInput()
 546
 547    def __str__(self):
 548        return repr(self.value)
 549
 550    def __validateInput(self):
 551        def validate_key_val(key, val):
 552            if not isinstance(key, str):
 553                raise Exception(f"key in IdentifierToColumnMapping {key} was not a string!")
 554            if not isinstance(val, ColumnSubRole):
 555                raise Exception(f"val in IdentifierToColumnMapping {val} was not a ColumnSubRole!")
 556
 557        for key, val in self.mapping:
 558            validate_key_val(key, val)
 559
 560
 561class PortfolioSettings:
 562    """
 563    This config is a documentation wrapper around a dict representing the portfolio settings json.
 564    Keys missing in the dict provided will fallback to the listed default when updating the
 565    the portfolio settings on the server.
 566
 567    Parameters
 568    ----------
 569    activeRisk: bool
 570        - **Active Risk**:
 571            Set the portfolio optimization parameters to be relative to the score from the stock
 572            universe. i.e. if you set Momentum to 0.5 to 1.0 and the stock universe has a market cap
 573            weighed score of 0.2 then the optimizer will solve for 0.7 to 1.2.
 574        - Constraints:
 575            Boolean value
 576        - Default Value: false
 577
 578    allowCompanyCollisions: bool
 579        - **Allow Multiple Securities Per Company**:
 580            Allows the machine to trade multiple securities (at the same time) for the same company.
 581            If it is ON and a company has listed PREF shares and COMMON shares, both will show up as
 582            tradeable options for that company. If it is OFF then system will try to determine the
 583            "correct" security to trade based on volume, liquidity, and share type.
 584        - Constraints:
 585            Boolean value
 586        - Default Value: true
 587
 588    allowDR: bool
 589        - **Allow Depositary Receipts**:
 590            Companies with tickers ending in .Y and .F will be disallowed from trading within the
 591            model with this setting off. Turn it on to allow trading in these securities.
 592        - Constraints:
 593            Boolean value
 594        - Default Value: true
 595
 596    benchmark: array
 597        - **Benchmark**:
 598            Set one or more benchmarks and the weighting for each.
 599        - Constraints:
 600            Required.
 601            List of dicts with keys:
 602            gbi_id: integer representing the GBI ID of the benchmark index.
 603            weight: floating point value between 0 and 1.
 604            All gbi_id's in the dictionary must be unique, and the benchmark weights must sum to a
 605            number between 0 and 1.
 606        - Default Value: []
 607
 608    benchmarkAllocation: float
 609        - **Benchmark Allocation**:
 610            None
 611        - Constraints:
 612            Floating point value representing a percentage between -100 and 100
 613        - Default Value: 0
 614
 615    beta_neutral: bool
 616        - **Beta Neutral**:
 617            Adjust the weights to get the ex-ante Beta to be the net exposure of the portfolio. i.e.
 618            70% Long / 30% Short = 0.4 Beta"
 619        - Constraints:
 620            Boolean value
 621        - Default Value: false
 622
 623    bounds_method: str | null
 624        - **Optimizer Bounds**:
 625            Tight: The optimizer will only allow the weightings of securities in your portfolio to
 626            stay tight (close) to their initial weighting.
 627            Loose: The optimizer will allow the weightings of securities in your portfolio to move a
 628            medium amount more from their initial weighting.
 629            Wide: The optimizer will allow almost any weight between the minimum and maximum weight
 630            per long or short position.
 631        - Constraints:
 632            String enum of {loose, tight, wide}, or null
 633        - Default Value: null
 634
 635    compounding: bool
 636        - **Compound Returns**:
 637            When toggled on, this will allow the portfolio to compound returns.
 638        - Constraints:
 639            Boolean value
 640        - Default Value: true
 641
 642    currency: str
 643        - **Currency**:
 644            The currency you would like your portfolio to be calculated in. Note that if the
 645            currency differs from its exchange (i.e. GBP on the S&P), the prior close foreign
 646            exchange rate will be used for calculations.
 647        - Constraints:
 648            String representing a 3 digit ISO currency code.
 649        - Default Value: "USD"
 650
 651    equalWeightBenchmark: bool
 652        - **Equal Weight Benchmark**:
 653            Instead of using the defined benchmarks, set the benchmark to be an equal weighted (per
 654            rebalance period) version of the stock universe.
 655        - Constraints:
 656            Boolean value
 657        - Default Value: false
 658
 659    executionDelay: int
 660        - **Execution Delay**:
 661            This option adds the number of days selected to the trade execution. If you select T+1
 662            and your rebalance period is set to Weekly (Monday), it will trade on Tuesday, and so
 663            on.
 664        - Constraints:
 665            Integer value between 0 and 100, inclusive.
 666        - Default Value: 0
 667
 668    factorNeutralizeSignal: bool
 669        - **Signal Optimizer**:
 670            Turn on optimization at the signal level that will adjust signals and rankings according
 671            to the specifications you set. This is done prior to portfolio construction and can help
 672            reduce bias in the model.
 673        - Constraints:
 674            Boolean value
 675        - Default Value: false
 676
 677    investmentHorizon: int
 678        - **Investment Horizon**:
 679            The investment horizon for the portfolio.
 680        - Constraints:
 681            An integer representing a number of days
 682        - Default Value: 21
 683
 684    lower_turnover: bool
 685        - **Lower Turnover**:
 686            If toggled on the optimizer will try to solve the secondary goal of optimizing the
 687            primary goals while limiting turnover.
 688        - Constraints:
 689            Boolean value
 690        - Default Value: false
 691
 692    marketCapBounds: float
 693        - **Maximum Market Cap Variation**:
 694            How far from the target market cap weighted index each stock can deviate (positive or
 695            negative).
 696        - Constraints:
 697            Floating point value representing a percentage between 0 and 10
 698        - Default Value: 1
 699
 700    marketCapConstraint: bool
 701        - **Constrain Market Cap**:
 702            Force weighting to be near the target weights for a market cap weighted index of your
 703            entire stock universe.
 704        - Constraints:
 705            Boolean value
 706        - Default Value: false
 707
 708    marketCapFlex: float
 709        - **Market Cap Flex**:
 710            How far from the target market cap weighted the stock can deviate relative to the
 711            existing weight (i.e. at 75% a 1% position cannot exceed 1.75%).
 712        - Constraints:
 713            Floating point value representing a percentage between 10 and 200
 714        - Default Value: 100
 715
 716    maxLongPosition: float
 717        - **Max Long Position per Stock**:
 718            The maximum weighting of a long position within the portfolio.
 719        - Constraints:
 720            Required. Floating point value representing a percentage between 0.0 and 300.0
 721        - Default Value: 10.0
 722
 723    maxNumStockLong: int
 724        - **Maximum Number of Longs**:
 725            The maximum number of stocks to buy. This is on a per “portfolio” basis, so if you have
 726            sector neutral turned on it will be maximum per sector.
 727        - Constraints:
 728            Integer value between 0 and 1000, inclusive. Must be >= minNumStockLong
 729        - Default Value: 50
 730
 731    maxNumStockShort: int
 732        - **Maximum Number of Shorts**:
 733            The maximum number of stocks to short. This is on a per “portfolio” basis, so if you
 734            have sector neutral turned on it will be maximum per sector.
 735        - Constraints:
 736            Integer value between 0 and 1000, inclusive. Must be >= minNumStockShort
 737        - Default Value: 50
 738
 739    maxOwnership: float
 740        - **Maximum Ownership**:
 741            The maximum percentage of a company the portfolio is allowed to own. For example, if a
 742            company had a market cap of $100MM and this was 5% the portfolio could not own more than
 743            $5MM of that company.
 744        - Constraints:
 745            Floating point value representing a percentage between 0 and 100
 746        - Default Value: 5
 747
 748    maxShortPosition: float
 749        - **Max Short Position per Stock**:
 750            The maximum weighting of a short position within the portfolio.
 751        - Constraints:
 752            Required. Floating point value representing a percentage between 0.0 and 300.0
 753        - Default Value: 5.0
 754
 755    minimumSharePrice: float
 756        - **Minimum Share Price**:
 757            The minimum share price you want the portfolio to allow.
 758        - Constraints:
 759            Floating point value between 0 and 100000
 760        - Default Value: 2
 761
 762    minLongPosition: float
 763        - **Min Long Position per Stock**:
 764            The minimum weighting of a long position within the portfolio.
 765        - Constraints:
 766            Floating point value representing a percentage between 0.0 and 300.0
 767        - Default Value: 0
 768
 769    minNumStockLong: int
 770        - **Minimum Number of Longs**:
 771            The minimum number of stocks to buy. This is on a per “portfolio” basis, so if you have
 772            sector neutral turned on it will be minimum per sector.
 773        - Constraints:
 774            Integer value between 0 and 1000, inclusive. Must be <= maxNumStockLong
 775        - Default Value: 5
 776
 777    minNumStockShort: int
 778        - **Minimum Number of Shorts**:
 779            The minimum number of stocks to short. This is on a per “portfolio” basis, so if you
 780            have sector neutral turned on it will be minimum per sector.
 781        - Constraints:
 782            Integer value between 0 and 1000, inclusive. Must be <= maxNumStockShort
 783        - Default Value: 5
 784
 785    minShortPosition: float
 786        - **Min Short Position per Stock**:
 787            The minimum weighting of a short position within the portfolio.
 788        - Constraints:
 789            Floating point value representing a percentage between 0.0 and 100.0
 790        - Default Value: 0
 791
 792    missingMarketCap: float
 793        - **Missing Market Cap**:
 794            The amount in millions (MM) to replace any missing market capitalization information
 795            with. This will impact the maximum ownership setting.
 796        - Constraints:
 797            Floating point value between 0 and 100
 798        - Default Value: 10
 799
 800    nameBasedSectorWeighting: bool
 801        - **Name Based Sector Weighting**:
 802            Base sector weightings on number of names. For example, if there are 200 names in the
 803            index and financials has 20 companies, the weight of financials should be 10% (20/200).
 804        - Constraints:
 805            Boolean value
 806        - Default Value: false
 807
 808    netBenchmark: bool
 809        - **Adjust Benchmark for Net Exposure**:
 810            If your portfolio has a net exposure greater or less than 100%, this will adjust the
 811            benchmark returns to match that net exposure.
 812        - Constraints:
 813            Boolean value
 814        - Default Value: false
 815
 816    optimizer: str
 817        - **Optimizer Type**:
 818            No Optimization: None
 819            Reduce Risk: Optimizer designed to reduce portfolio volatility. This tends to result in
 820            the best overall performance.
 821            Maximize Sharpe: Optimizer designed to maximize Sharpe using out of sample estimates for
 822            expected return. Estimates for expected return have an outsized impact on the
 823            performance of this optimizer.
 824            Maximize Alpha: Optimizer designed to maximize expected return based on out-of-sample
 825            estimates for expected return. Estimates for expected return have an outsized impact on
 826            the performance of this optimizer.
 827            Min VaR: Minimize Value at Risk by looking back at the proposed portfolio over the last
 828            year and trying to minimize drawdowns.
 829            Max VaR Sharpe: Maximize Value at Risk Sharpe by looking back at the proposed portfolio
 830            over the last year and trying to maximize Sharpe by observed return for the portfolio vs
 831            observed volatility.
 832            Minimize Skew: Minimize the skew of the portfolio by trying to find a set of portfolio
 833            weightings that results in returns that are closer to the mean.
 834        - Constraints:
 835            Required. String enum: one of
 836            default: No Optimization
 837            min_vol: Reduce Risk
 838            max_sharpe: Maximize Sharpe
 839            max_alpha: Maximize Alpha
 840            min_var: Min VaR
 841            max_var_sharpe: Max VaR Sharpe
 842            min_skew: Minimize Skew
 843        - Default Value: "default"
 844
 845    optimizeTurnover: bool
 846        - **Turnover Optimization**:
 847            Turnover optimization will reduce the turnover at the signal level, making that ranked
 848            list more stable.
 849        - Constraints:
 850            Boolean value
 851        - Default Value: false
 852
 853    pairsTrading: bool
 854        - **Pairs Trading**:
 855            Pairs Trading forces the portfolio to be created by going long / short an equal number
 856            of stocks. The portfolio will try to find an offsetting position for every long by
 857            finding securities that are both highly correlated and have a significant difference in
 858            star rating.
 859        - Constraints:
 860            Boolean value
 861        - Default Value: false
 862
 863    percentPortfolioLong: float
 864        - **Percent of Portfolio Long**:
 865            The exact sum of all long position weightings in the portfolio.
 866        - Constraints:
 867            Required. Floating point value representing a percentage between 0.0 and 300.0
 868        - Default Value: 100.0
 869
 870    percentPortfolioShort: float
 871        - **Percent of Portfolio Short**:
 872            The exact sum of all short position weightings in the portfolio.
 873        - Constraints:
 874            Required. Floating point value representing a percentage between 0.0 and 300.0
 875        - Default Value: 0.0
 876
 877    percentToLong: float
 878        - **Percent to Long**:
 879            The machine will attempt to buy the top X% of stocks, subject to the minimum and maximum
 880            specified. This is on a per “portfolio” basis, so if you have sector neutral turned on
 881            it will be top X% per sector. This will be subject to the maximum and minimum number of
 882            securities you specify below.
 883        - Constraints:
 884            Floating point value representing a percentage between 0 and 100
 885        - Default Value: 20.0
 886
 887    percentToShort: float
 888        - **Percent to Short**:
 889            The machine will attempt to short the bottom X% of stocks, subject to the minimum and
 890            maximum specified. This is on a per “portfolio” basis, so if you have sector neutral
 891            turned on it will be bottom X% per sector. This will be subject to the maximum and
 892            minimum number of securities you specify below.
 893        - Constraints:
 894            Floating point value representing a percentage between 0 and 100
 895        - Default Value: 20.0
 896
 897    portfolioStartingValue: float
 898        - **Portfolio Starting Value**:
 899            The value of the portfolio in MM when it begins trading. If its backtest spans from 2005
 900            - 2020, the starting value in 2005 will be whatever you set here.
 901        - Constraints:
 902            Floating point value between 0 and 100000.
 903        - Default Value: 100.0
 904
 905    priceCleaning: bool
 906        - **Price Cleaning**:
 907            Price Cleaning removes any very large price movements from the securities, specifically
 908            with a daily change greater than +500% or -83.33%. There are some legitimate securities
 909            with moves this large that will be impacted by turning this on, but the advantage is it
 910            prevents these securities from overwhelming the backtest.
 911        - Constraints:
 912            Boolean value
 913        - Default Value: true
 914
 915    priceType: str
 916        - **Price Type**:
 917            None
 918        - Constraints:
 919            Required. String enum of {CLOSE, OPEN, VWAP}
 920        - Default Value: "VWAP"
 921
 922    rebalancePeriod: str
 923        - **Rebalance Period**:
 924            When the machine rebalances the portfolio. You can choose a specific day if you prefer
 925            to execute trades on a specific day.
 926        - Constraints:
 927            Required.
 928            An enum value in the following list:
 929            "daily"
 930            "weekly": Rebalances on every Monday.
 931            Chooses the next available trade date to rebalance when Monday is a holiday
 932            "weekly_wednesday": Rebalances on every Wednesday.
 933            Chooses the next available trade date to rebalance when Wednesday is a holiday
 934            "weekly_friday": Rebalances on every Friday.
 935            Chooses the previous available trade date to rebalance when Friday is a holiday
 936            "monthly"
 937            "quarterly"
 938            OR a string in the following format: "custom_x" where x is an integer between 1 and 252
 939            (days).
 940        - Default Value: "weekly"
 941
 942    sectorNeutral: bool
 943        - **Sector Neutral**:
 944            Will be constructed as a series of portfolios - each matching the market cap weighting
 945            of each of the stock universe sectors. This means that min. and max. number of stocks
 946            "per portfolio" becomes "per sector".
 947        - Constraints:
 948            Boolean value
 949        - Default Value: false
 950
 951    sectorNeutralEqualWeightBenchmark: bool
 952        - **Sector Neutral Equal Weight Benchmark**:
 953            Instead of using the defined benchmarks, set the benchmark to be a "sector neutral"
 954            equal weighted (per rebalance period) version of the stock universe. This takes the
 955            sector weighting and divides by the number of stocks in that sector, so each sector will
 956            have a different individual security weighting.
 957        - Constraints:
 958            Boolean value
 959        - Default Value: false
 960
 961    sectorNeutralSpread: float
 962        - **Sector Neutral Spread**:
 963            The sector neutral spread is how far away from the benchmark sector allocation the
 964            machine can deviate. This is adjusted for net exposure, i.e. if your net exposure is 0%
 965            the target sector allocations will be 0%.
 966        - Constraints:
 967            Floating point value representing a percentage between 0 and 100
 968        - Default Value: 0
 969
 970    signalIndustryNeutral: bool
 971        - **Industry Neutral**:
 972            Make the signal industry neutral, plus or minus the signal sector neutral spread.
 973        - Constraints:
 974            Boolean value
 975        - Default Value: false
 976
 977    signalSectorNeutral: bool
 978        - **Sector Neutral**:
 979            Make the signal sector neutral, plus or minus the signal sector neutral spread.
 980        - Constraints:
 981            Boolean value
 982        - Default Value: false
 983
 984    signalSectorNeutralSpread: float
 985        - **Sector Neutral Spread**:
 986            Make the signal sector neutral, plus or minus the signal sector neutral spread.
 987        - Constraints:
 988            Floating point value representing a percentage between 0 and 100
 989        - Default Value: 1.0
 990
 991    smoothPeriods: int
 992        - **Smooth Periods**:
 993            The number of periods over which to smooth the signals
 994        - Constraints:
 995            Integer value between 1 and 100.
 996        - Default Value: 1
 997
 998    smoothWeighting: str
 999        - **Smooth Weighting Type**:
1000            Alpha Weight: The strength of the signal matters in the smoothing. For example, if a
1001            stock had a score of 5 stars in period A, 2 stars in period B, your 2 period smoothing
1002            would be 7 / 2 = 3.5.
1003            Equal Weight: Only the direction of the signal matters here. For example, if you were 5
1004            stars in period A and 2 stars in period B, your 2 period smoothing would be 0 / 2 = 0
1005            (+1 in period 1 and -1 in period 2)
1006        - Constraints:
1007            One of {alpha_weight, equal_weight}
1008        - Default Value: "alpha_weight"
1009
1010    stopGain: bool
1011        - **Enable Stop Gain**:
1012            Turn on stop gains for the portfolio. This forces sales of securities that have exceeded
1013            the stop gain level. All trades will occur at the next trading time (i.e. next day OPEN
1014            for OPEN price models).
1015        - Constraints:
1016            Boolean value
1017        - Default Value: false
1018
1019    stopGainAmount: float
1020        - **Stop Gain Percentage to Sell**:
1021            The percentage of the position the machine will sell if the stop gain is triggered.
1022        - Constraints:
1023            Floating point value representing a percentage between 1 and 100.
1024        - Default Value: 50.0
1025
1026    stopGainLevel: float
1027        - **Stop Gain Threshold**:
1028            Will sell positions after they hit a threshold. For example, 10% / stop gain, when a
1029            position gains 10% the machine will sell a portion of the position (defined by stop gain
1030            percentage).
1031        - Constraints:
1032            Floating point value representing a percentage between 1 and 100.
1033        - Default Value: 10.0
1034
1035    stopLoss: bool
1036        - **Enable Stop Loss**:
1037            Turn on stop losses for the portfolio. This forces sales of securities that have
1038            exceeded the stop loss level. All trades will occur at the next trading time (i.e. next
1039            day OPEN for OPEN price models).
1040        - Constraints:
1041            Boolean value
1042        - Default Value: false
1043
1044    stopLossAmount: float
1045        - **Stop Loss Percentage to Sell**:
1046            The percentage of the position the machine will sell if the stop loss is triggered.
1047        - Constraints:
1048            Floating point value representing a percentage between 1 and 100.
1049        - Default Value: 50.0
1050
1051    stopLossLevel: float
1052        - **Stop Loss Threshold**:
1053            Will sell positions after they hit a threshold. For example, 10% / stop loss, when a
1054            position loses 10% the machine will sell a portion of the position (defined by stop loss
1055            percentage).
1056        - Constraints:
1057            Floating point value representing a percentage between 1 and 100.
1058        - Default Value: 10.0
1059
1060    stopLossReset: bool
1061        - **Allow multiple stop loss/gain between rebalance days**:
1062            Allows the machine to repeatedly trigger stop losses within a rebalance period. For
1063            example, if you trade Mondays and the stock drops 15% per day during the week and the
1064            stop loss trigger is 10%, then every day will trigger the stop loss. If toggled off the
1065            stop loss can only be triggered once per stock per rebalance period.
1066        - Constraints:
1067            Boolean value
1068        - Default Value: false
1069
1070    trackingConstraint: float
1071        - **Maximum Tracking Error (vs Benchmark)**:
1072            Amount of ex-ante tracking error to constrain the optimizer by.
1073        - Constraints:
1074            Floating point value representing a percentage between 0 and 30
1075        - Default Value: 10
1076
1077    trackingError: bool
1078        - **Allocate Weight to Benchmark**:
1079            Allocate a portion (%) of portfolio to the benchmark
1080        - Constraints:
1081            Boolean value
1082        - Default Value: false
1083
1084    trackingErrorOptimizer: bool
1085        - **Tracking Error**:
1086            If toggled on the optimizer will try to solve for an expected tracking error less than
1087            the amount specified. This is done out-of-sample and the ex post tracking error will
1088            likely be higher.
1089        - Constraints:
1090            Boolean value
1091        - Default Value: false
1092
1093    tradingCost: float
1094        - **Trading Cost**:
1095            A cost that will be applied to every trade.
1096        - Constraints:
1097            Required. Floating point value representing a percentage between 0.0 and 5.0
1098        - Default Value: 0.01
1099
1100    turnoverImportance: float
1101        - **Turnover Importance**:
1102            High importance means the algorithm will aim to keep turnover low, whereas low
1103            importance of turnover will let it vary more.
1104        - Constraints:
1105            Floating point value between 0.2 and 5 nonlinearly mapped onto the 1-9 interval.
1106        - Default Value: 1
1107
1108    useHoldingPeriod: bool
1109        - **Use Holding Period**:
1110            Set any covariance or other calculations within the optimizer to use a holding period
1111            return instead of daily return series
1112        - Constraints:
1113            Boolean value
1114        - Default Value: false
1115
1116    weightingType: str
1117        - **Initial Weighting**:
1118            Alpha Weight: The initial weighting will be done such that higher ranked stocks have a
1119            higher weight.
1120            Equal Weight: The initial weighting will be done such that all stocks selected to be in
1121            the portfolio will have an equal weight.
1122            Market Cap Weight: The initial weighting will be done such that all stocks are weighted
1123            according to their previous day’s market capitalization.
1124        - Constraints:
1125            One of {alpha_weight, equal_weight, market_cap_weight}
1126        - Default Value: "alpha_weight"
1127    """
1128
1129    # note, this is just the collection of portfolio settings
1130    # that is exposed to the API:
1131    # SELECT key, default_value
1132    # FROM portfolio_settings_validation
1133    # WHERE exposed_to_client_api;
1134    # TODO: expand to entire settings? why this way initially?
1135    __default_settings = {
1136        "maxOwnership": "5",
1137        "pairsTrading": "false",
1138        "minNumStockLong": "5",
1139        "stopLossAmount": "50.0",
1140        "stopGainLevel": "10.0",
1141        "smoothWeighting": '"alpha_weight"',
1142        "minimumSharePrice": "2",
1143        "maxShortPosition": "5.0",
1144        "tradingCost": "0.01",
1145        "stopGainAmount": "50.0",
1146        "smoothPeriods": "1",
1147        "executionDelay": "0",
1148        "benchmarkAllocation": "0",
1149        "sectorNeutralSpread": "0",
1150        "percentToLong": "20.0",
1151        "maxNumStockLong": "50",
1152        "trackingConstraint": "10",
1153        "compounding": "true",
1154        "priceCleaning": "true",
1155        "lower_turnover": "false",
1156        "missingMarketCap": "10",
1157        "allowCompanyCollisions": "true",
1158        "allowDR": "true",
1159        "sectorNeutral": "false",
1160        "marketCapFlex": "100",
1161        "marketCapBounds": "1",
1162        "turnoverImportance": "1",
1163        "minNumStockShort": "5",
1164        "maxNumStockShort": "50",
1165        "beta_neutral": "false",
1166        "nameBasedSectorWeighting": "false",
1167        "trackingError": "false",
1168        "stopLoss": "false",
1169        "stopGain": "false",
1170        "stopLossReset": "false",
1171        "netBenchmark": "false",
1172        "equalWeightBenchmark": "false",
1173        "marketCapConstraint": "false",
1174        "signalIndustryNeutral": "false",
1175        "signalSectorNeutral": "false",
1176        "sectorNeutralEqualWeightBenchmark": "false",
1177        "percentToShort": "20.0",
1178        "trackingErrorOptimizer": "false",
1179        "currency": '"USD"',
1180        "rebalancePeriod": '"weekly"',
1181        "benchmark": "[]",
1182        "signalSectorNeutralSpread": "1.0",
1183        "optimizeTurnover": "false",
1184        "minShortPosition": "0",
1185        "minLongPosition": "0",
1186        "percentPortfolioLong": "100.0",
1187        "portfolioStartingValue": "100.0",
1188        "stopLossLevel": "10.0",
1189        "maxLongPosition": "10.0",
1190        "percentPortfolioShort": "0.0",
1191        "bounds_method": None,
1192        "optimizer": '"default"',
1193        "activeRisk": "false",
1194        "useHoldingPeriod": "false",
1195        "weightingType": '"alpha_weight"',
1196        "priceType": '"VWAP"',
1197        "factorNeutralizeSignal": "false",
1198        "investmentHorizon": "21",
1199    }
1200
1201    def __init__(self, settings: Optional[Dict] = None):
1202        # TODO: i'd rather have kwargs for the different keys and then allow
1203        # for per-key overrides, but we start with this more conservative approach
1204        if settings is None:
1205            self.settings = copy.deepcopy(PortfolioSettings.__default_settings)
1206        else:
1207            self.settings = settings
1208
1209    def toDict(self):
1210        return self.settings
1211
1212    def __str__(self):
1213        return json.dumps(self.settings)
1214
1215    def __repr__(self):
1216        return self.__str__()
1217
1218    def fromDict(settings):
1219        return PortfolioSettings(settings)
1220
1221
1222hedge_experiment_type = Literal["HEDGE", "MIMIC"]
1223
1224
1225@dataclass(frozen=True)  # from _python client's_ perspective, instances will never change!
1226class HedgeExperiment:
1227    id: str  # really a uuid, which we represent as a string
1228    name: str
1229    user_id: str  # see id comment
1230    description: str
1231    experiment_type: hedge_experiment_type  # TODO: enum worth it?
1232    last_calculated: dt.datetime
1233    last_modified: dt.datetime
1234    status: str  # TODO: enum worth it?
1235    portfolio_calculation_status: str  # TODO: enum worth it?
1236    selected_models: List[str]  # see id comment
1237    target_securities: Dict[GbiIdSecurity, float]  # Security is a hashable type because frozen=True
1238    target_portfolios: List[str]
1239    selected_stock_universe_ids: List[str]  # see id comment
1240    baseline_model: Optional[str] = None
1241    baseline_stock_universe_id: Optional[str] = None
1242    baseline_scenario: Optional["HedgeExperimentScenario"] = None
1243
1244    @property
1245    def config(self) -> Dict:
1246        """
1247        Returns a hedge experiment configuration dictionary, ready for JSON-serialization and
1248        submission.
1249        """
1250        weights_by_gbiid = [
1251            {"gbiId": sec.id, "weight": weight} for sec, weight in self.target_securities.items()
1252        ]
1253        return {
1254            "experimentType": self.experiment_type,
1255            "selectedModels": self.selected_models,
1256            "targetSecurities": weights_by_gbiid,
1257            "selectedStockUniverseIds": self._selected_stock_universe_ids,
1258        }
1259
1260    @classmethod
1261    def from_json_dict(cls, d: Dict) -> "HedgeExperiment":
1262        # drafts arent fully populated
1263        if d["status"] == "DRAFT":
1264            weights_by_security = {}
1265            selected_models = []
1266            selected_stock_universe_ids = []
1267        else:
1268            weights_by_security = {
1269                GbiIdSecurity(
1270                    sec_dict["gbiId"],
1271                    None,
1272                    sec_dict["security"]["symbol"],
1273                    sec_dict["security"]["name"],
1274                ): sec_dict["weight"]
1275                for sec_dict in d["targetSecurities"]
1276            }
1277            experiment_config = json.loads(d["config"])
1278            selected_models = experiment_config["selectedModels"]
1279            selected_stock_universe_ids = experiment_config["selectedStockUniverseIds"]
1280        baseline_scenario = None
1281        if d["baselineScenario"] is not None:
1282            baseline_scenario = HedgeExperimentScenario.from_json_dict(d["baselineScenario"])
1283        return cls(
1284            d["hedgeExperimentId"],
1285            d["experimentName"],
1286            d["userId"],
1287            d["description"],
1288            d["experimentType"],
1289            d["lastCalculated"],
1290            d["lastModified"],
1291            d["status"],
1292            d["portfolioCalcStatus"],
1293            selected_models,
1294            weights_by_security,
1295            d.get("targetPortfolios"),
1296            selected_stock_universe_ids or [],
1297            d.get("baselineModel"),
1298            d.get("baselineStockUniverseId"),
1299            baseline_scenario,
1300        )
1301
1302
1303@dataclass(frozen=True)
1304class HedgeExperimentScenario:
1305    id: str  # really a uuid, which we represent as a string;
1306    name: str
1307    description: str
1308    status: str  # TODO: enum worth it?
1309    settings: PortfolioSettings
1310    summary: pd.DataFrame
1311    # we currently a portfolios field. they get wrapped up into the summary table
1312
1313    @classmethod
1314    def from_json_dict(cls, d: Dict) -> "HedgeExperimentScenario":
1315        return cls(
1316            d["hedgeExperimentScenarioId"],
1317            d["scenarioName"],
1318            d["description"],
1319            d.get("status"),
1320            PortfolioSettings(json.loads(d["portfolioSettingsJson"])),
1321            HedgeExperimentScenario._build_portfolio_summary(d.get("hedgeExperimentPortfolios")),
1322        )
1323
1324    @staticmethod
1325    def _build_portfolio_summary(portfolios: Dict) -> pd.DataFrame:
1326        # this happens for added scenarios that havent run yet
1327        if portfolios is None:
1328            return pd.DataFrame()
1329
1330        df_dict = defaultdict(list)
1331        for pf in portfolios:
1332            p = pf["portfolio"]
1333
1334            df_dict["portfolio_id"].append(p["id"])
1335            df_dict["scenario_name"].append(p["name"])
1336            df_dict["model_id"].append(p["modelId"])
1337            df_dict["status"].append(p["status"])
1338
1339            if p["status"] != "READY":  # data isn't yet available
1340                df_dict["1M"].append(np.nan)
1341                df_dict["3M"].append(np.nan)
1342                df_dict["1Y"].append(np.nan)
1343                df_dict["sharpe"].append(np.nan)
1344                df_dict["vol"].append(np.nan)
1345            else:
1346                # NOTE:
1347                # these are the magic indices/keys of these values; inspect passed arg to see
1348                # if upstream changes the order of (sub-)elements in the response...uh oh
1349                # TODO: specific key search? wrap with try/except and fail loudly?
1350                df_dict["1M"].append(p["performanceGrid"][0][4])
1351                df_dict["3M"].append(p["performanceGrid"][0][5])
1352                df_dict["1Y"].append(p["performanceGrid"][0][7])
1353                df_dict["sharpe"].append(p["tearSheet"][0]["members"][1]["value"])
1354                pf_stddev = p["tearSheet"][1]["members"][1]["value"]
1355                bnchmk_stddev = p["tearSheet"][1]["members"][2]["value"]
1356                df_dict["vol"].append((pf_stddev - bnchmk_stddev) * 100)
1357                # TODO: this is how it is done on the front-end,
1358                # should be pulled out of both here and there
1359
1360        df = pd.DataFrame(df_dict)
1361        return df
1362
1363
1364@dataclass(frozen=True)  # from _python client's_ perspective, instances will never change!
1365class HedgeExperimentDetails:
1366    # this will probably lead to violations of the law of demeter, but it's easy to do right now,
1367    # particularly for an unproven API
1368    experiment: HedgeExperiment
1369    scenarios: Dict[str, HedgeExperimentScenario]
1370
1371    @property
1372    def summary(self) -> pd.DataFrame:
1373        """
1374        Returns a dataframe corresponding to the Hedge Experiment "flat view" - all portfolio
1375        options are displayed
1376        """
1377        if len(self.scenarios) == 0 or all(s.status != "READY" for s in self.scenarios.values()):
1378            return pd.DataFrame()
1379        return pd.concat(scenario.summary for scenario in self.scenarios.values()).sort_values(
1380            ["scenario_name"]
1381        )  # sort for stable presentation
1382
1383    @classmethod
1384    def from_json_dict(cls, d: Dict) -> "HedgeExperimentDetails":
1385        he = HedgeExperiment.from_json_dict(d)
1386        scenarios = {
1387            scenario_dict["hedgeExperimentScenarioId"]: HedgeExperimentScenario.from_json_dict(
1388                scenario_dict
1389            )
1390            for scenario_dict in d["hedgeExperimentScenarios"]
1391        }
1392        return cls(he, scenarios)