Wednesday, July 27, 2011

Creating Financial Instrument metadata in R

(This is a guest post by Ilya Kipnis)

When trading stocks in a single currency, instrument metadata can be safely ignored because the multiplier is 1 and the currencies are all the same.  When doing analysis on fixed income products, options, futures, or other complex derivative instruments, the data defining the properties of these instruments becomes critical to tasks like accounting for value of trades, or comparing notional value between more than one instrument. The FinancialInstrument package provides a construct for storing metadata for tradeable contracts (referred to as instruments, e.g. stocks, futures, options, etc.) and their root representations.  It can be used to create any asset class and complex derivatives, across multiple currencies. 

In tactical asset allocation using blotter, Joshua Ulrich used FinancialInstrument (blotter depends on it) to create a stock portfolio.  FinancialInstrument is also a required dependency of the quantstrat quantitative strategy framework in R (quantstrat will be covered in a later post).

Creating a list of historical symbols is a recurring challenge with historical data on derivative instruments.  These symbols tend to follow a deterministic pattern and FinancialInstrument provides utility functions to create the symbols traded over specific periods of time. These symbols could then be used to request historical data from a data vendor or to construct instrument objects in R.

The simplest function for generating a series of symbols is build_series_symbols.  Let's look at it with a small example using crude oil (CL) and STOXX (STXE) futures:

    # install.packages("FinancialInstrument", repos="")
    Data <- data.frame(primary_id="CL", month_cycle="F,G,H,J,K,M,N,Q,U,V,X,Z")
    Data <- rbind(Data, data.frame(primary_id="STXE", month_cycle="H,M,U,Z"))
    #   primary_id               month_cycle
    # 1         CL   F,G,H,J,K,M,N,Q,U,V,X,Z
    # 2       STXE                   H,M,U,Z

The Data object contains two columns.  The primary_id is the root contract that identifies the instrument, and the month_cycle defines the months the contracts trade in (e.g. “H,M,U,Z” for Mar/Jun/Sep/Dec).

build_series_symbols only needs Data and yearlist.   yearlist is the suffix for expiration years and 0, 1, 2 represent 2010, 2011, 2012 in this example.  build_series_symbols returns a vector of series symbols that we could use to request data or create future_series instruments.

    build_series_symbols(Data, yearlist=c(0,1,2))
     [1] "CLF0"   "CLG0"   "CLH0"   "CLJ0"   "CLK0"   "CLM0"   "CLN0"   "CLQ0" 
     [9] "CLU0"   "CLV0"   "CLX0"   "CLZ0"   "STXEH0" "STXEM0" "STXEU0" "STXEZ0"
    [17] "CLF1"   "CLG1"   "CLH1"   "CLJ1"   "CLK1"   "CLM1"   "CLN1"   "CLQ1" 
    [25] "CLU1"   "CLV1"   "CLX1"   "CLZ1"   "STXEH1" "STXEM1" "STXEU1" "STXEZ1"
    [33] "CLF2"   "CLG2"   "CLH2"   "CLJ2"   "CLK2"   "CLM2"   "CLN2"   "CLQ2" 
    [41] "CLU2"   "CLV2"   "CLX2"   "CLZ2"   "STXEH2" "STXEM2" "STXEU2" "STXEZ2"

A more complicated task is to create symbols for exchange guaranteed calendar spreads.  The build_spread_symbols function creates a vector of symbols for spreads of securities (currently coded for futures calendar spreads but can be extended and generalized) in a very shorthand notation.

build_spread_symbols accepts instrument specifications via either a file path or (preferably) a data frame (using the file or data arguments, respectively). Output can be assigned to an object or written to a file using the optional outputfile argument.  The default starting date is the current date, but the user can manually set a starting date (e.g. historical dates for backtesting, and future dates to create lists of instruments to be traded in the future).

    # read in data that would be suitable for load.instruments on root contracts
    Data <- read.csv("series_data.csv", stringsAsFactors=FALSE)
    # set the type to guaranteed_spread
    Data$type <- "guaranteed_spread"
    # call build_spread_symbols
    output <- build_spread_symbols(Data[6:7,], start_date="2010-01-01")

The critical fields in the data (CSV or data frame) are the primary_id, the type (e.g. future, calendar spread, intercommodity spread, etc.), the month_cycle, and the active_months (how many contracts to display).  For instance, an active_months value of 12 on a contract that trades quarterly (“H,M,U,Z”) would create front month contracts for the next 3 years.  An active_months value of 6 on this same quarterly contract would produce 1.5 years.  On a contract that trades 12 months a year (“F,G,H,J,K,M,N,Q,U,V,X,Z”), an active_months value of 12 would produce 1 year of contracts, and a value of 6 would only produce half a year.

Lastly, the contracts_ahead field specifies the month spread on calendar spread type securities.  Note that these are contracts ahead and not months ahead.  For example, if you consider a contract trading “H,M,U,Z” vs. a contract trading “F,G,H,J,K,M,N,Q,U,V,X,Z”, a value of 1 for the “H,M,U,Z” contract would create an H1-M1 spread or the like, while a value of 1 with the 12-month traded contract would create an F1-G1 spread.

The rest of the columns simply get carried over, for further use in other programs/scripts/procedures, such as the load.instruments function.

About the Author: Ilya Kipnis holds a Master's degree in Statistics from Rutgers, and uses and contributes to the R packages blotter, FinancialInstrument, and quantstrat. Ilya may be contacted for consulting and full-time opportunities in finance at


Anonymous said...

Should we consider it good that rules are independent of model building? I don't think so. My goal in backtesting is to assign a PROBABILITY that a trade will move my favour -- and then size according to modified Kelly.

Brian G. Peterson said...

@crasshopper: I think it would be more appropriate to say that rules are ipart of the model, and that models are independent of the instruments that they will be applied to. Nothing in this is antithetical to trade sizing with a LSPM or modified Kelly methodology once you are able to quantify your edge based on your backtests and production tests on small lot sizes.

Howard anthony said...

BUPA FINANCE PLC is a group of company with funding experts and mandate to a finance and investment Company who is a premier provider of trade finance and project finance instruments as well as discountable bank instruments.

Our bank instrument can be help you fund you projects in Trading, funding project(s) such as Aviation, Agriculture, Petroleum, Telecommunication, construction of Dams, Bridges, Real Estate and all kind of projects.Having years of professional, invaluable experience in the banking and finance industry, and having access to dozens of different prominent trusted and reliable providers, our Financial Services consultants will crawl through hundreds of products to find one that perfectly matches your needs.

Purchase Instrument of BG/SBLC : 32%+2% Min Face Value cut =5M- 10B EUR/USD

Lease Instrument of BG/SBLC : 4%+2% Min Face Value cut = 5M- 10B EUR/USD

1. Instrument: Bank Guarantee (BG / SBLC) (Appendix A)
2. Total Face Value: Eur 5M MIN and Eur 10B MAX (Ten Billion USD).
3. Issuing Bank: HSBC Bank London, Barclays, Credit Suisse and Deutsche Bank Frankfurt.
4. Age: One Year, One Month
5. Leasing Price: 6% of Face Value plus 2% commission fees to brokers.
6. Delivery: Bank to Bank swift.
7. Payment: MT-103 or MT760
8. Hard Copy: Bonded Courier within 7 banking days.

Name :Howard Anthony

Skype ID:92f864467edaf0b8