{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "Examples require an initialized GsSession and relevant entitlements. `run_analytics` scope is required for the functionality covered in this tutorial. External clients need to substitute thier own client id and client secret below. Please refer to Sessions for details." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "from gs_quant.session import GsSession\n", "GsSession.use(client_id=None, client_secret=None, scopes=('run_analytics',))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## What is an Instrument\n", "\n", "[`Instrument`](https://developer.gs.com/docs/gsquant/api/instrument.html) is a class that inherits from the [`Priceable`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html)\n", "class and is used to represent financial objects that can be priced, such as derivative instruments.\n", "\n", "[`Priceable`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable/) exposes several methods common to all instruments, such as [`as_dict()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.as_dict) which returns a dictionary of all the public, non-null properties and values and\n", "[`calc(risk_measure)`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.calc) which is used to evaluate various risk measures. More about the latter in the [Measures](https://developer.gs.com/docs/gsquant/guides/Pricing-and-Risk/measures/) guide.\n", "\n", "`gs-quant` offers a number of [`Instrument`](https://developer.gs.com/docs/gsquant/api/instrument.html#instruments/) implementations, such as [equity options](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.EqOption.html#gs_quant.instrument.EqOption/), [interest rate swaptions](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRSwaption.html#gs_quant.instrument.IRSwaption/) and [commodity swaps](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.CommodSwap.html).\n", "Please refer to [supported instruments](#supported-instruments) for a list of externally supported instruments." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## How to Create an Instrument\n", "\n", "Let's now create an instance of an instrument implementation.\n", "For this example, we will create an Interest Rate Swaption, which the [`IRSwaption`](/gsquant/api/classes/gs_quant.instrument.IRSwaption.html#gs_quant.instrument.IRSwaption/) class implements.\n", "\n", "We will start by importing [`IRSwaption`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRSwaption.html#gs_quant.instrument.IRSwaption/) from the [`Instrument`](https://developer.gs.com/docs/gsquant/api/instrument.html#instruments/) package as well as `PayReceive`, `Currency` to represent commonly used constants.\n" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "from gs_quant.instrument import IRSwaption\n", "from gs_quant.common import PayReceive, Currency" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We will now instantiate an [`IRSwaption`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRSwaption.html#gs_quant.instrument.IRSwaption/) object. Note that all [`Instruments`](https://developer.gs.com/docs/gsquant/api/instrument.html#instruments/), including [`IRSwaption`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRSwaption.html#gs_quant.instrument.IRSwaption/), take some non-keyworded required arguments (first 3 in this example),\n", "and some optional keyworded arguments (\\*\\*kwargs). If the optional arguments are not supplied, default market conventions will be used as described in each\n", "instrument's signature. Signatures can be found in the [the Instrument Package](/gsquant/api/instrument.html#instruments/) by clicking\n", "on the desired instrument." ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "swaption = IRSwaption(PayReceive.Receive, '5y', Currency.USD, expiration_date='13m', strike='atm+40', notional_amount=1e8)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can now use the [`as_dict()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.as_dict) method inherited from [`Priceable`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#) to view all public non-null properties and values of this swaption instance." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "swaption.as_dict()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Instrument Resolution\n", "\n", "The above output shows only the inputs specified, many of which are relative (i.e. expiration date, strike). Calling the [`resolve()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.resolve) method will resolve these\n", "parameters to absolute values as well as fill in any defaulted parameters using the [`PricingContext`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.markets.PricingContext.html). Please refer to the above mentioned [Instrument Package](/gsquant/api/instrument.html#instruments/) for each instrument's available parameters and to the [Pricing Context guide](/gsquant/guides/Pricing-and-Risk/pricing-context) for further details on [`PricingContext`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.markets.PricingContext.html)." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "swaption.resolve()\n", "swaption.as_dict()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note [`resolve()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.resolve) will change the state of the instrument object. In the code snippet above, calling [`resolve()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.resolve) mutates several specified relative parameters, for example:\n", "\n", "- `expiration_date`, specified as '13m', was resolved to '2020-11-02'\n", "- `strike` specified as 'atm+40', was resolved to '0.017845989434194357'\n", "\n", "[`resolve()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.resolve) will also add any unspecified default parameters - note the additions when calling [`as_dict()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.as_dict) before and after [`resolve()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.resolve). For example:\n", "\n", "- 'fixed_rate_frequency': '6m'\n", "- 'premium_payment_date': '2019-10-04'\n", "\n", "Accessing any of the unspecified parameters on the unresolved swaption will resolve the swaption in place.\n", "\n", "Additionally, as discussed in the [measures guide](/gsquant/guides/Pricing-and-Risk/measures), if [`resolve()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.resolve) is not called prior to calling [`price()`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.base.Priceable.html#gs_quant.base.Priceable.price) or calculating risk, the instrument object will be copied and resolved on the fly without mutating the original swaption object.\n", "\n", "The preferred behavior may depend on the [`PricingContext`](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.markets.PricingContext.html#gs_quant.markets.PricingContext/) - more on this in the [Pricing Context](/gsquant/guides/Pricing-and-Risk/pricing-context) guide." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "## Supported Instruments\n", "\n", "Below are the instruments covered, names they are referred to as in gs_quant and brief definitions as well as links to\n", " the technical documentation for each. Each instrument corresponds to a model maintained by Goldman Sachs Securities Division.\n", "\n", "| Instrument | gs_quant name | Description |\n", "| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------|\n", "| Eq Option | [EqOption](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.EqOption.html) | An option on an underlying equity security |\n", "| FX Forward | [FXForward](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.FXForward.html) | An exchange of cashflows in different currencies at a determined future time |\n", "| FX Option | [FXOption](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.FXOption.html) | An option on an FX Forward |\n", "| FX Binary | [FXBinary](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.FXBinary.html) | An option where the buyer receives a fixed amount if a certain currency pair fixes above or below a specified level on a specified date. |\n", "| FX Multi Cross Binary | [FXMultiCrossBinary](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.FXMultiCrossBinary.html) | An option where the buyer receives a fixed amount if each of the currency pairs fixes above or below a specified level on a specified date. |\n", "| FX Volatility Swap | [FXVolatilitySwap](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.FXVolatilitySwap.html) | An exchange of cashflows based on the realized volatility of the underlying FX cross and a pre-determined fixed volatility level |\n", "| Inflation Swap | [InflationSwap](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.InflationSwap.html) | A zero coupon vanilla inflation swap of fixed vs floating cashflows adjusted to inflation rate |\n", "| Interest Rate Swap | [IRSwap](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRSwap.html) | A vanilla interest rate swap of fixed vs floating cashflows in the same currency |\n", "| Interest Rate Basis Swap | [IRBasisSwap](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRBasisSwap.html) | An exchange of cashflows from different interest rate indices in the same currency |\n", "| Interest Rate Xccy Swap | [IRXccySwap](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRXccySwap.html) | An exchange of cashflows from different interest rate indices in different currencies |\n", "| Interest Rate Xccy Swap Fix Fix | [IRXccySwapFixFix](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRXccySwapFixFix.html) | An exchange of fixed cashflows in different currencies |\n", "| Interest Rate Xccy Swap Fix Float | [IRXccySwapFixFlt](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRXccySwapFixFlt.html) | A vanilla interest rate swap of fixed vs floating cashflows in different currencies |\n", "| Interest Rate Swaption | [IRSwaption](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRSwaption.html) | An option to enter into a vanilla interest rate swap of fixed vs floating cashflows |\n", "| Interest Rate Cap | [IRCap](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRCap.html) | An instrument in which the buyer receives payments at the end of each period in which the interest rate exceeds the agreed strike price |\n", "| Interest Rate Floor | [IRFloor](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRFloor.html) | An instrument in which the buyer receives payments at the end of each period in which the interest rate is below the agreed strike price |\n", "| Interest Rate CMS Option | [IRCMSOption](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRCMSOption.html) | An option on a single date where the payoff is based on the CMS rate |\n", "| Interest Rate CMS Option Strip | [IRCMSOptionStrip](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRCMSOptionStrip.html) | A strip of CMS Options |\n", "| Interest Rate CMS Spread Option | [IRCMSSpreadOption](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRCMSSpreadOption.html) | An option on a single date where the payoff is dependent on the spread of two CMS rates compared to the strike of the option. |\n", "| Interest Rate CMS Spread Option Strip | [IRCMSSpreadOptionStrip](https://developer.gs.com/docs/gsquant/api/classes/gs_quant.instrument.IRCMSSpreadOptionStrip.html) | A strip of CMS Spread Options |\n", "\n", "Note that `IRDelta` is additional available for Interest Rate Futures and Bond Futures upon request.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Disclaimer\n", "This website may contain links to websites and the content of third parties (\"Third Party Content\"). We do not monitor, review or update, and do not have any control over, any Third Party Content or third party websites. We make no representation, warranty or guarantee as to the accuracy, completeness, timeliness or reliability of any Third Party Content and are not responsible for any loss or damage of any sort resulting from the use of, or for any failure of, products or services provided at or from a third party resource. If you use these links and the Third Party Content, you acknowledge that you are doing so entirely at your own risk.\n" ] } ], "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.2" } }, "nbformat": 4, "nbformat_minor": 4 }