gs_quant/documentation/06_baskets/tutorials/Basket Edit.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Editing a Custom Basket\n",
    "\n",
    "Editing a custom basket is very similar to the creation process. You simply fetch your basket, set its properties to match your preferences, and call update! Please note that not all settings are modifiable after creation (see the list of options below). Additionally, if you'd like to adjust your basket's composition or price settings, please refer to the [rebalance tutorial](./Basket%20Rebalance.ipynb) instead."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 1: Authenticate & Initialize your session\n",
    "\n",
    "First you will import the necessary modules and add your client id and client secret."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gs_quant.markets.baskets import Basket\n",
    "from gs_quant.session import Environment, GsSession\n",
    "\n",
    "client = 'CLIENT ID'\n",
    "secret = 'CLIENT SECRET'\n",
    "\n",
    "GsSession.use(Environment.PROD, client_id=client, client_secret=secret, scopes=('read_product_data read_user_profile modify_product_data',))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Fetch your basket and set your changes\n",
    "\n",
    "Next you will fetch the basket you'd like to edit by passing in any of its identifiers such as BloombergId, Cusip, Ticker, etc. If this is a basket you or someone from your organization created, please make sure your application has edit/admin entitlements or you will not be able to modify it. You will then be ready to change any of the properties listed below.\n",
    "\n",
    "| Parameter Name      |Description |\n",
    "|:--------------------|:-----------|\n",
    "|name                 |Display name of the basket|\n",
    "|description          |Free text description of basket. Description provided will be indexed in the search service for free text relevance match.|\n",
    "|publish_to_bloomberg |If you'd like us to publish your basket to Bloomberg|\n",
    "|publish_to_reuters   |If you'd like us to publish your basket to Reuters  |\n",
    "|publish_to_factset   |If you'd like us to publish your basket to Factset  |\n",
    "|include_price_history|Republish price history based on current composition|\n",
    "|cash_reinvestment_treatment|How to treat cash acquisitions, regular dividends, and special dividends for basket underliers.|\n",
    "|historical_methodology|Preferred methodology to be applied when publishing basket history.<ul><li>**Backcast**: Apply current composition backwards up to 5 years, assuming constituent shares remained constant</li><li>**Backtest**: Reset composition based on the selected criteria and rebalance frequency over selected period of time. Must specify these options in `backtest_parameters`.</li><li>**Custom History**: Upload your own basket history after the basket has been created. *Note: Previously this was indicated by setting* `default_backcast = False`</li></ul>|\n",
    "|backtest_parameters  |Rules applied when performing a historical backtest.<ul><li>**Weighting Mechanism**: On each rebalance date, whether to reset positions to have equal weights or restore based on original position set values.</li><li>**Time Horizon**: Time horizon for which to generate historical backtest. (5 years is the only supported option at this time.)</li><li>**Frequency**: Frequency at which to recalculate position shares (Weekly, Monthly, Quarterly, Annually.)</li></ul>|"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "basket = Basket.get('GSMBXXXX')\n",
    "\n",
    "basket.description = 'My New and Improved basket description'\n",
    "basket.publish_to_reuters = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Update your basket's entitlements\n",
    "\n",
    "The application you use to create your basket will initially be the only one permissioned to view, edit, and submit rebalance requests. If you'd like to entitle other users or groups with view or admin access, you may update your basket's permissions at any time.\n",
    "\n",
    "In order to add or remove permissions for a specific user, you will need either their Marquee user id or email. You may also permission groups using their group id. See the snippet below, or refer to the [baskets permissions examples](../examples/07_basket_permissions/0001_permission_application_to_basket.ipynb) for more options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gs_quant.entities.entitlements import Group, User\n",
    "\n",
    "user = User.get(user_id='application_id')\n",
    "basket.entitlements.view.users.remove(user)\n",
    "\n",
    "group = Group.get(group_id='group_id')\n",
    "basket.entitlements.admin.groups += [group]\n",
    "\n",
    "basket.entitlements.to_frame() # call to verify the entitlement changes are now reflected properly"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Submit your changes\n",
    "\n",
    "Once you've ensured that your basket has been updated to your satisfaction, you're ready to officially submit these changes to Marquee! Once you call update on the basket, you may poll its status to make sure that it has processed successfully. This will check the report status every 30 seconds for 10 minutes by default, but you can override this option if you prefer as shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_basket.get_details() # call to make sure that your changes are all reflected properly\n",
    "\n",
    "my_basket.update()\n",
    "\n",
    "my_basket.poll_status(timeout=120, step=20) # optional: constantly checks edit status until report succeeds, fails, or the poll times out (this example checks every 20 seconds for 2 minutes)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}