Package 'FinancialInstrument'

Description

Extract a single row from each day in an xts object

Usage

.to_daily(x, EOD_time = "15:00:00")

Arguments

Value

xts object with daily scale.

Author(s)

Garrett See

See Also

quantmod:::to.daily, quantmod:::to.period

Description

Concatenate a string or strings (passed through dots) to the defined.by field of an instrument (separated by semi-colons). Any duplicates will be removed. See Details.

Usage

add.defined.by(primary_ids, ...)

Arguments

Details

If there is already a value for the defined.by attribute of the primary_id instrument, that string will be split on semi-colons and converted to a character vector. That will be combined with any new strings (in ...). The unique value of this new vector will then be converted into a semi-colon delimited string that will be assigned to the defined.by attribute of the primary_ids' instruments

Many functions that create or update instrument definitions will also add or update the value of the defined.by attribute of that instrument. If an instrument has been updated by more than one function, it's defined.by attribute will likely be a semi-colon delimited string (e.g. “TTR;yahoo”).

Value

called for side-effect

Author(s)

Garrett See

See Also

add.identifier, instrument_attr

Examples

## Not run: 
update_instruments.TTR("GS")
getInstrument("GS")$defined.by #TTR
add.defined.by("GS", "gsee", "demo")
add.defined.by("GS", "gsee;demo") #same

## End(Not run)

Description

Add an identifier to an instrument unless the instrument already has that identifier.

Usage

add.identifier(primary_id, ...)

Arguments

Value

called for side-effect

Author(s)

Garrett See

See Also

instrument_attr

Examples

## Not run: 
stock("XXX", currency("USD"))
add.identifier("XXX", yahoo="^XXX")
getInstrument("^XXX")
add.identifier("^XXX", "x3")
all.equal(getInstrument("x3"), getInstrument("XXX")) #TRUE

## End(Not run)

Description

The columns needed by this version of the function are primary_id and month_cycle. primary_id should match the primary_id of the instrument describing the root contract. month_cycle should contain a comma delimited string describing the month sequence to use, e.g. "F,G,H,J,K,M,N,Q,U,V,X,Z" for all months using the standard futures letters, or "H,M,U,Z" for quarters, or "Mar,Jun,Sep,Dec" for quarters as three-letter month abbreviations, etc. The correct values will vary based on your data source.

Usage

build_series_symbols(roots, yearlist = c(0, 1))

Arguments

Details

TODO add more flexibility in input formats for roots

Value

A character vector containing the constructed series identifiers. Each identifier combines a root contract identifier, a contract-month code, and a year suffix.

Author(s)

Brian G. Peterson

See Also

load.instruments

Description

The columns needed by this version of the function are primary_id, month_cycle, and code contracts_ahead.

Usage

build_spread_symbols(
  data = NULL,
  file = NULL,
  outputfile = NULL,
  start_date = Sys.Date()
)

Arguments

Details

primary_id should match the primary_id of the instrument describing the root contract.

month_cycle should contain a comma delimited string describing the month sequence to use, e.g. "F,G,H,J,K,M,N,Q,U,V,X,Z" for all months using the standard futures letters, or "H,M,U,Z" for quarters, or "Mar,Jun,Sep,Dec" for quarters as three-letter month abbreviations, etc. The correct values will vary based on your data source.

contracts_ahead should contain a comma-delimited string describing the cycle on which the guaranteed calendar spreads are to be consructed, e.g. '1' for one-month spreads, '1,3' for one and three month spreads, '1,6,12' for 1, 6, and 12 month spreads, etc. For quarterly symbols, the correct contracts_ahead may be something like '1,2,3' for quarterly, bi-annual, and annual spreads.

active_months is a numeric field indicating how many months including the month of the start_date the contract is available to trade. This number will be used as the upper limit for symbol generation.

If type is also specified, it should be a specific instrument type, e.g. 'future_series','option_series','guaranteed_spread' or 'calendar_spread'

One of data or file must be populated for input data.

Value

If 'outputfile' is 'NULL', a data frame with columns 'symbol' and 'type', containing the constructed spread identifiers and their instrument types. If 'outputfile' is supplied, the data frame is written to that CSV file and the function returns 'NULL' invisibly.

Author(s)

Ilya Kipnis <Ilya.Kipnis<at>gmail.com>

See Also

load.instruments build_series_symbols

Description

Construct a hierarchy of instruments useful for aggregation

Usage

buildHierarchy(primary_ids, ...)

Arguments

Value

Constructs a data.frame that contains the list of assets in the first column and the category or factor for grouping at each level in the following columns

Author(s)

Peter Carl, Alexis Petit, Garrett See

See Also

instrument.table

Examples

## Not run: 
# rm_instruments(keep.currencies=FALSE)
## Define some stocks
update_instruments.TTR(c("XOM", "IBM", "CVX", "WMT", "GE"), exchange="NYSE")

buildHierarchy(ls_instruments(), "type")
buildHierarchy(ls_stocks(), c("Name", "Sector"))
buildHierarchy(ls_stocks(), "Industry", "MarketCap")

## End(Not run)

Description

Calculates time series of ratio of 2 instruments using available data. Returned object will be ratios calculated using Bids, Asks, and Mids, or Opens, Closes, and Adjusteds.

Usage

buildRatio(x, env = .GlobalEnv, silent = FALSE)

Arguments

Details

x should be a vector of 2 instrument names. An attempt will be made to get the data for both instruments. If there are no xts data stored under either of the names, it will try to return prebuilt data with a call to .get_rate.

If the data are not of the same frequency, or are not of the same type (OHLC, BBO, etc.) An attempt will be made to make them compatible. Preference is given to the first leg.

If the data in x[1] is daily or slower and the data in x[2] is intraday (e.g. if you give it daily OHLC and intraday Bid Ask Mid, it will use all of the OHLC columns of x[1] and only the the End of Day Mid price of the BAM object.

If the data in x[1] is intraday, and the data in x[2] is daily or slower, for each day, the previous closing value of x[2] will be filled forward with na.locf

Value

An xts object with columns of Bid, Ask, Mid OR Open, Close, Adjusted OR Price

Author(s)

Garrett See

See Also

redenominate buildSpread fn_SpreadBuilder

Examples

## Not run: 
syms <- c("SPY","DIA")
getSymbols(syms)
rat <- buildRatio(syms)
summary(rat)

## End(Not run)

Description

Build price series for spreads, butterflies, or other synthetic instruments, using metadata of a previously defined synthetic instrument.

Usage

buildSpread(
  spread_id,
  Dates = NULL,
  onelot = TRUE,
  prefer = NULL,
  auto.assign = TRUE,
  env = .GlobalEnv
)

buildBasket(
  spread_id,
  Dates = NULL,
  onelot = TRUE,
  prefer = NULL,
  auto.assign = TRUE,
  env = .GlobalEnv
)

Arguments

Details

The spread and all legs must be defined instruments.

This function can build multileg spreads such as calendars, butterflies, condors, etc. However, the returned series will be univariate. It does not return multiple columns (e.g. ‘Bid’, ‘Ask’, ‘Mid’) like fn_SpreadBuilder does.

buildBasket is an alias

TODO: allow for multiplier (divisor) that is a vector.

Value

If auto.assign is FALSE, a univariate xts object. Otherwise, the xts object will be assigned to spread_id and the spread_id will be returned.

Note

this could also be used to build a basket or a strip by using only positive values in memberratio

Author(s)

Brian Peterson, Garrett See

See Also

fn_SpreadBuilder spread for instructions on defining the spread

Examples

## Not run: 
currency("USD")
stock("SPY","USD",1)
stock("DIA","USD",1)
getSymbols(c("SPY","DIA")) 

spread("SPYDIA", "USD", c("SPY","DIA"),c(1,-1)) #define it.
buildSpread('SPYDIA') #build it.
head(SPYDIA)


## End(Not run)

Description

Convert month code (used for futures contracts) to abbreviated month name, or convert abbreviated month name to month code

Usage

C2M(code)

M2C(month)

Arguments

Value

corresponding code or month.

Author(s)

Garrett See

See Also

MC2N

Examples

C2M()
C2M("M")
C2M()[6]
M2C()
M2C("Sep")
M2C()[9]

Description

Compare the .instrument environments of two files

Usage

CompareInstrumentFiles(file1, file2, ...)

Arguments

Details

This will load two instrument files (created by saveInstruments) and find the differences between them. In addition to returning a list of difference that are found, it will produce messages indicating the number of instruments that were added, the number of instruments that were removed, and the number of instruments that are different.

Value

A list that contains the names of all instruments that were added, the names of all instruments that were removed, and the changes to all instruments that were updated (per all.equal.instrument).

Author(s)

Garrett See

See Also

saveInstruments, all.equal.instrument

Examples

example_dir <- tempfile("fi-compare-")
dir.create(example_dir)

backup_name <- "backup.RData"
file1_name <- "instruments1.RData"
file2_name <- "instruments2.RData"

backup_path <- file.path(example_dir, backup_name)
file1_path <- file.path(example_dir, file1_name)
file2_path <- file.path(example_dir, file2_name)

saveInstruments(backup_name, dir = example_dir)

tryCatch(
  {
    stopifnot(file.exists(backup_path))

    rm_instruments(keep.currencies = FALSE)
    currency("USD")
    stock(c("SPY", "DIA", "GLD"), currency = "USD")
    saveInstruments(file1_name, dir = example_dir)

    stopifnot(file.exists(file1_path))

    rm_stocks("GLD")
    stock("QQQ", currency = "USD")
    instrument_attr(
      "SPY",
      "description",
      "S&P 500 ETF"
    )
    saveInstruments(file2_name, dir = example_dir)

    stopifnot(file.exists(file2_path))

    CompareInstrumentFiles(file1_path, file2_path)
  },
  finally = {
    if (file.exists(backup_path)) {
      reloadInstruments(backup_name, dir = example_dir)
    }

    unlink(example_dir, recursive = TRUE)
  }
)

currency metadata to be used by load.instruments

Description

currency metadata to be used by load.instruments

Description

Currency symbols (like any symbol) may be any combination of alphanumeric characters, but the FX market has a convention that says that the first currency in a currency pair is the 'target' and the second currency in the symbol pair is the currency the rate ticks in. So 'EURUSD' can be read as 'USD per 1 EUR'.

Usage

exchange_rate(
  primary_id = NULL,
  currency = NULL,
  counter_currency = NULL,
  tick_size = 0.01,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...
)

Arguments

Details

In FinancialInstrument the currency of the instrument should be the currency that the spot rate ticks in, so it will typically be the second currency listed in the symbol.

Thanks to Garrett See for helping sort out the inconsistencies in different naming and calculating conventions.

Value

When 'assign_i = TRUE', a character vector containing the 'primary_id' values of the exchange-rate instruments assigned to the registry. When 'assign_i = FALSE', an exchange-rate instrument object is returned for scalar input, or a list of such objects for vectorized input.

References

https://www.investopedia.com/terms/b/basecurrency.asp

Description

Currently, there are methods for instrument, spread, character, and xts

Usage

expires(x, ...)

Arguments

Details

Will return either the last expiration date before a given Date, or the first expiration date after a given Date (if expired==FALSE).

If an instrument contains a value for expires that does not include a day (e.g. "2012-03"), or if the expires value is estimated from a future_series primary_id, it will be assumed that the instrument expires on the first of the month (i.e. if the expires value of an instrument were "2012-03", or if there were no expires value but the suffix_id were "H12", the value returned would be "2012-03-01"). Note that most non-energy future_series expire after the first of the month indicated by their suffix_id and most energy products expire in the month prior to their suffix_id month.

Value

an expiration Date

Author(s)

Garrett See

See Also

expires.instrument, expires.character, sort_ids

getInstrument and buildHierarchy to see actual values stored in instrument

Examples

instr <- instrument("FOO_U1", currency=currency("USD"), multiplier=1,
                    expires=c("2001-09-01", "2011-09-01", "2021-09-01"),
                    assign_i=FALSE)
#Last value of expires that's not after Sys.Date
expires(instr)
# First value of expires that hasn't already passed.
expires(instr, expired=FALSE)
# last value that's not after 2011-01-01
expires(instr, Date="2011-01-01")
# first value that's not before 2011-01-01
expires(instr, Date="2011-01-01", expired=FALSE)

## expires.character
expires("FOO_U1") # warning that FOO_U1 is not defined
instrument("FOO_U1", currency=currency("USD"), multiplier=1,
           expires=c("2001-09-01", "2011-09-01", "2021-09-01"),
           assign_i=TRUE)
expires("FOO_U1")

Description

Uses regular expression matching to find instruments

Usage

find.instrument(
  text,
  where = "anywhere",
  Symbols = ls_instruments(),
  ignore.case = TRUE,
  exclude = NULL,
  ...
)

Arguments

Value

character vector of primary_ids of instruments that contain the sought after text.

Author(s)

Garrett See

See Also

buildHierarchy, instrument.table, regex

Examples

backup_file <- tempfile(fileext = ".RData")
saveInstruments(backup_file)

tryCatch(
  {
    rm_instruments(keep.currencies = FALSE)

    currency(c("USD", "EUR"))
    stock("SPY", "USD", description = "S&P 500 ETF")
    stock("DIA", "USD", description = "DJIA ETF")
    stock(
      c("AA", "AXP", "BA", "BAC", "CAT"),
      "USD",
      members.of = "DJIA"
    )
    stock("BMW", "EUR")

    find.instrument("ETF")
    find.instrument("DJIA")
    find.instrument("DJIA", where = "members.of")
    find.instrument("USD")
    find.instrument("EUR", Symbols = ls_stocks())
  },
  finally = {
    reloadInstruments(backup_file)
    unlink(backup_file)
  }
)

Description

Find attributes that more than one instrument have in common

Usage

FindCommonInstrumentAttributes(Symbols, ...)

Arguments

Value

character vector of names of attributes that all Symbols' instruments have in common

Note

I really do not like the name of this function, so if it survives, its name may change

Author(s)

gsee

Description

Given 2 products, calculate spread values for as many columns as practicable.

Usage

fn_SpreadBuilder(
  prod1,
  prod2,
  ratio = 1,
  currency = "USD",
  from = NULL,
  to = NULL,
  session_times = NULL,
  notional = TRUE,
  unique_method = c("make.index.unique", "duplicated", "least.liq", "price.change"),
  silent = FALSE,
  auto.assign = TRUE,
  env = .GlobalEnv,
  ...
)

Arguments

Details

prod1 and prod2 can be the names of instruments, or the xts objects themselves. Alternatively, prod2 can be omitted, and a vector of 2 instrument names can be given to prod1. See the last example for this usage.

If prod1 and prod2 are names (not xts data), it will try to get data for prod1 and prod2 from env (.GlobalEnv by default). If it cannot find the data, it will get it with a call to getSymbols. Prices are multiplied by multipliers and exchange rates to get notional values in the currency specified. The second leg's notional values are multiplied by ratio. Then the difference is taken between the notionals of leg1 and the new values for leg2.

‘make.index.unique’ uses the xts function make.index.unique ‘least.liq’ subsets the spread time series, by using the timestamps of the leg that has the fewest rows. ‘duplicated’ removes any duplicate indexes. ‘price.change’ only return rows where there was a price change in the Bid, Mid or Ask Price of the spread.

Value

an xts object with Bid, Ask, Mid columns, or Open, Close, Adjusted columns, or Open, Close columns. or Price column.

Note

requires quantmod

Author(s)

Lance Levenson, Brian Peterson, Garrett See

See Also

buildSpread synthetic.instrument formatSpreadPrice buildRatio

Examples

## Not run: 
currency("USD")
stock("SPY", "USD")
stock("DIA", "USD")
getSymbols(c("SPY","DIA"))

#can call with names of instrument/xts ojects
fSB <- fn_SpreadBuilder("SPY","DIA") 
fSB2 <- fn_SpreadBuilder(SPY,DIA) # or you can pass xts objects

#assuming you first somehow calculated the ratio to be a constant 1.1
fSB3 <- fn_SpreadBuilder("SPY","DIA",1.1) 
head(fSB)

# Call fn_SpreadBuilder with vector of 2 instrument names
# in 1 arg instead of using both prod1 and prod2.
fSB4 <- fn_SpreadBuilder(c("SPY","DIA"))
#download data and plot the closing values of a spread in one line
chartSeries(Cl(fn_SpreadBuilder(getSymbols(c("SPY","DIA")),auto.assign=FALSE)))

## End(Not run)

Description

convert the primary_id or suffix_id of an instrument to a different format. Primarily intended for future_series instruments.

Usage

format_id(id, format = NULL, parse = c("id", "suffix"), sep = "_", ...)

Arguments

Details

Formats for the suffix_id include 'CY', 'CYY', and 'CYYYY' where C is the month code and Y is numeric. 'MMMY', 'MMMYY', 'MMMYYYY' where MMM is an uppercase month abbreviation. '1xCY', '1xCYY', '1xCYYYY' for single-stock-futures.

There are currently only 2 formats available for option_series: 'opt2' and 'opt4' where opt2 uses a 2 digit year and opt4 uses a 4 digit year.

Value

character id of the appropriate format

Author(s)

Garrett See

See Also

parse_id, parse_suffix, M2C, month_cycle2numeric

Examples

format_id('U1', format='MMMYY', parse='suffix')
format_id('ES_JUN2011', format='CYY', parse='id')
format_id("SPY_20110826P129","opt2")
#several at once
id3 <- c('VX_aug1','ES_U1', 'VX_U11')
format_id(id3,'MMMYY')
format_id(id3,'CYY')
format_id(id3,'CY',sep="")

Description

Divides the notional spread price by the spread multiplier and rounds prices to the nearest tick_size.

Usage

formatSpreadPrice(x, multiplier = 1, tick_size = 0.01)

Arguments

Value

price series of same length as x

Author(s)

Garrett See

See Also

buildSpread, fn_SpreadBuilder

Description

Constructors for series contracts on instruments such as options and futures

Usage

future_series(
  primary_id,
  root_id = NULL,
  suffix_id = NULL,
  first_traded = NULL,
  expires = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...
)

option_series(
  primary_id,
  root_id = NULL,
  suffix_id = NULL,
  first_traded = NULL,
  expires = NULL,
  callput = c("call", "put"),
  strike = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...
)

bond_series(
  primary_id,
  suffix_id,
  ...,
  first_traded = NULL,
  maturity = NULL,
  identifiers = NULL,
  payment_schedule = NULL,
  assign_i = TRUE
)

Arguments

Details

The root instrument (e.g. the future or option) must be defined first.

In custom parameters for these series contracts, we have often found it useful to store attributes such as local roll-on and roll-off dates (rolling not on the first_listed or expires.

For future_series and option_series you may either provide a primary_id (or vector of primary_ids), OR both a root_id and suffix_id.

Note that the code for bond and bond_series has not been updated recently and may not support all the features supported for option_series and future_series. Patches welcome.

Value

For 'future_series()' and 'option_series()', a character vector of assigned 'primary_id' values when 'assign_i = TRUE', or an instrument object for scalar input and a list of instrument objects for vectorized input when 'assign_i = FALSE'. 'bond_series()' returns the result of creating or updating the bond-series instrument; this is normally the assigned identifier for a newly created series.

Examples

currency("USD")
future("ES","USD",multiplier=50, tick_size=0.25)
future_series('ES_U1')
future_series(root_id='ES',suffix_id='Z11')
stock('SPY','USD')
option('.SPY','USD',multiplier=100,underlying_id='SPY')
#can use either .SPY or SPY for the root_id.
#it will find the one that is option specs.
option_series('SPY_110917C125', expires='2011-09-16')
option_series(root_id='SPY',suffix_id='111022P125')
option_series(root_id='.SPY',suffix_id='111119C130')
#multiple series instruments at once.
future_series(c("ES_H12","ES_M12"))
option_series(c("SPY_110917C115","SPY_110917P115"))

Description

This function will search the .instrument environment for objects of class type, using first the primary_id and then any identifiers to locate the instrument. Finally, it will try adding 1 and then 2 dots to the beginning of the primary_id to see if an instrument was stored there to avoid naming conflicts.

Usage

getInstrument(x, Dates = NULL, silent = FALSE, type = "instrument")

Arguments

Details

future and option objects may have a primary_id that begins with 1 or 2 dots (in order to avoid naming conflics). For example, the root specs for options (or futures) on the stock with ticker "SPY" may be stored with a primary_id of "SPY", ".SPY", or "..SPY". getInstrument will try using each possible primary_id until it finds an instrument of the appropriate type

Value

An object inheriting from the requested instrument class when a matching instrument is found. Returns 'FALSE' when no matching instrument is found.

Examples

option('..VX', multiplier=100,
        underlying_id=future('.VX',multiplier=1000,
        underlying_id=synthetic('VIX', currency("USD")))
        )

getInstrument("VIX")
getInstrument('VX') #returns the future
getInstrument("VX",type='option')
getInstrument('..VX') #finds the option

Description

This function should probably get folded back into getSymbols.rda in quantmod.

Usage

getSymbols.FI(
  Symbols,
  from = getOption("getSymbols.FI.from", "2010-01-01"),
  to = getOption("getSymbols.FI.to", Sys.Date()),
  ...,
  dir = getOption("getSymbols.FI.dir", ""),
  return.class = getOption("getSymbols.FI.return.class", "xts"),
  extension = getOption("getSymbols.FI.extension", "rda"),
  split_method = getOption("getSymbols.FI.split_method", c("days", "common")),
  use_identifier = getOption("getSymbols.FI.use_identifier", NA),
  date_format = getOption("getSymbols.FI.date_format"),
  verbose = getOption("getSymbols.FI.verbose", TRUE),
  days_to_omit = getOption("getSymbols.FI.days_to_omit", c("Saturday", "Sunday")),
  indexTZ = getOption("getSymbols.FI.indexTZ", NA)
)

Arguments

Details

Meant to be called internally by getSymbols .

The symbol lookup table will most likely be loaded by setSymbolLookup.FI

If date_format is NULL (the Default), we will assume an ISO date as changed by make.names, for example, 2010-12-01 would be assumed to be a file containing 2010.12.01

If indexTZ is provided, the data will be converted to that timezone

If auto.assign is FALSE, Symbols should be of length 1. Otherwise, getSymbols will give you an error that says “must use auto.assign=TRUE for multiple Symbols requests” However, if you were to call getSymbols.FI directly (which is NOT recommended) with auto.assign=FALSE and more than one Symbol, a list would be returned.

Argument matching for this function is as follows. If the user provides a value for an argument, that value will be used. If the user did not provide a value for an argument, but there is a value for that argument for the given Symbol in the Symbol Lookup Table (see setSymbolLookup.FI), that value will be used. Otherwise, the formal defaults will be used.

Value

If 'auto.assign = TRUE', a character vector containing the names of the objects assigned to 'env'. If 'auto.assign = FALSE', an 'xts' object is returned for one requested symbol and a named list is returned for multiple symbols. Returns 'NULL' when no data are found.

See Also

saveSymbols.days instrument setSymbolLookup.FI loadInstruments getSymbols

Examples

example_dir <- tempfile("fi-symbol-data-")
dir.create(example_dir)

data_env <- new.env()

data_env$FI_EXAMPLE <- xts::xts(
  cbind(
    Close = c(100, 101, 102, 101),
    Volume = c(1000, 1200, 900, 1100)
  ),
  order.by = as.Date("2020-01-01") + 0:3
)

tryCatch(
  {
    saveSymbols.common(
      Symbols = "FI_EXAMPLE",
      base_dir = example_dir,
      env = data_env
    )

    loaded_data <- getSymbols.FI(
      Symbols = "FI_EXAMPLE",
      dir = example_dir,
      split_method = "common",
      auto.assign = FALSE,
      verbose = FALSE
    )

    stopifnot(
      xts::is.xts(loaded_data),
      NROW(loaded_data) == 4L,
      identical(
        colnames(loaded_data),
        c("Close", "Volume")
      )
    )

    loaded_data
  },
  finally = {
    unlink(example_dir, recursive = TRUE)
  }
)

Description

All 'currency' instruments must be defined before instruments of other types may be defined.

Usage

instrument(
  primary_id,
  ...,
  currency,
  multiplier,
  tick_size = NULL,
  identifiers = NULL,
  type = NULL,
  assign_i = FALSE,
  overwrite = TRUE
)

stock(
  primary_id,
  currency = NULL,
  multiplier = 1,
  tick_size = 0.01,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...
)

fund(
  primary_id,
  currency = NULL,
  multiplier = 1,
  tick_size = 0.01,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...
)

future(
  primary_id,
  currency,
  multiplier,
  tick_size = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...,
  underlying_id = NULL
)

option(
  primary_id,
  currency,
  multiplier,
  tick_size = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...,
  underlying_id = NULL
)

currency(primary_id, identifiers = NULL, assign_i = TRUE, ...)

bond(
  primary_id,
  currency,
  multiplier,
  tick_size = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...
)

Arguments

Details

In ... you may pass any other arbitrary instrument fields that will be used to create 'custom' fields. S3 classes in R are basically lists with a class attribute. We use this to our advantage to allow us to set arbitrary fields.

identifiers should be a named list to specify other identifiers beyond the primary_id. Please note that whenever possible, these should still be unique. Perhaps Bloomberg, Reuters-X.RIC, CUSIP, etc. getInstrument will return the first (and only the first) match that it finds, starting with the primary_id, and then searching the primary_ids of all instruments for each of the identifiers. Note that when a large number of instruments are defined, it is faster to find instruments by primary_id than by identifiers because it looks for primary_ids first.

The primary_id will be coerced within reason to a valid R variable name by using make.names. We also remove any leading '1' digit (a simple workaround to account for issues with the Reuters API). If you are defining an instrument that is not a currency, with a primary_id that already belongs to a currency, a new primary_id will be create using make.names. For example, stock("USD", currency("USD")), would create a stock with a primary_id of “USD.1” instead of overwritting the currency.

Please use some care to choose your primary identifiers so that R won't complain. If you have better regular expression code, we'd be happy to include it.

Identifiers will also try to be discovered as regular named arguments passed in via .... We currently match any of the following: "CUSIP","SEDOL","ISIN","OSI","Bloomberg","Reuters","X.RIC","CQG","TT","Yahoo","Google" Others may be specified using a named list of identifiers, as described above.

assign_i will use assign to place the constructed instrument class object into the .instrument environment. Most of the special type-specific constructors will use assign_i=TRUE internally. Calling with assign_i=FALSE, or not specifying it, will return an object and will not store it. Use this option ether to wrap calls to instrument prior to further processing (and presumably assignment) or to test your parameters before assignment.

If overwrite=FALSE is used, an error will be thrown if any primary_ids are already in use.

As of version 0.10.0, the .instrument environment is located at the top level of the package. i.e. .instrument.

future and option are used to define the contract specs of a series of instruments. The primary_id for these can begin with 1 or 2 dots if you need to avoid overwriting another instrument. For example, if you have a stock with ‘SPY’ as the primary_id, you could use ‘.SPY’ as the primary_id of the option specs, and ‘..SPY’ as the primary_id of the single stock future specs. (or vice versa)

You can (optionally) provide a src argument in which case, it will be used in a call to setSymbolLookup.

Value

When 'assign_i = TRUE', a character vector containing the 'primary_id' values of the instruments assigned to the instrument registry. When 'assign_i = FALSE', an instrument object is returned for scalar input; vectorized constructors return a list of instrument objects.

See Also

currency, exchange_rate, option_series, future_series, spread, load.instruments

Description

This function will add or overwrite the data stored in the specified slot of the specified instrument.

Usage

instrument_attr(primary_id, attr, value, ...)

Arguments

Details

If the attr you are trying to change is the “primary_id,” the instrument will be renamed. (A copy of the instrument will be stored by the name of value and the old instrument will be removed.) If the attr you are changing is “type”, the instrument will be reclassed with that type. If attr is “src”, value will be used in a call to setSymbolLookup. Other checks are in place to make sure that “currency” remains a currency object and that “multiplier” and “tick_size” can only be changed to reasonable values.

If attr is “identifiers” and value is NULL, identifiers will be set to list(). If value is not a list, add.identifier will be called with value. add.identifier will convert value to a list and append it to the current identifiers

Value

called for side-effect

Note

You can remove an attribute/level from an instrument by calling this function with value=NULL

Examples

## Not run: 
currency("USD")
stock("SPY","USD")
instrument_attr("USD","description","U.S. Dollar")
instrument_attr("SPY", "description", "An ETF")
getInstrument("USD")
getInstrument("SPY")

#Call with value=NULL to remove an attribute
instrument_attr("SPY", "description", NULL)
getInstrument("SPY")

instrument_attr("SPY","primary_id","SPX") #move/rename it
instrument_attr("SPX","type","synthetic") #re-class
instrument_attr("SPX","src",list(src='yahoo',name='^GSPC')) #setSymbolLookup
getSymbols("SPX") #knows where to look because the last line setSymbolLookup
getInstrument("SPX")

## End(Not run)

Description

Given a name, this function will attempt to create an instrument of the appropriate type.

Usage

instrument.auto(
  primary_id,
  currency = NULL,
  multiplier = 1,
  silent = FALSE,
  default_type = "unknown",
  root = NULL,
  assign_i = TRUE,
  ...
)

Arguments

Details

If currency is not already defined, it will be defined (unless it is not 3 uppercase characters). The default value for currency is “USD”. If you do not provide a value for currency, “USD” will be defined and used to create the instrument.

If primary_id is 6 uppercase letters and default_type is not provided, it will be assumed that it is the primary_id of an exchange_rate, in which case, the 1st and 2nd half of primary_id will be defined as currencys if not the names of already defined instruments. If the primary_id begins with a “^” it will be assumed that it is a yahoo symbol and that the instrument is an index (synthetic), and the ‘src’ will be set to “yahoo”. (see setSymbolLookup)

If it is not clear from the primary_id what type of instrument to create, an instrument of type default_type will be created (which is 'NULL' by default). This will happen when primary_id is that of a stock, future, option, or bond. This may also happen if primary_id is that of a future_series or option_series but the corresponding future or option cannot be found. In this case, the instrument type would be default_type, but a lot of things would be filled in as if it were a valid series instrument (e.g. ‘expires’, ‘strike’, ‘suffix_id’, etc.)

Value

Primarily called for its side-effect, but will return the name of the instrument that was created

Note

This is not intended to be used to create instruments of type stock, future, option, or bond although it may be updated in the future.

Author(s)

Garrett See

Examples

instrument.auto("CL_H1.U1")
getInstrument("CL_H1.U1") #guaranteed_spread

instrument.auto("ES_H1.YM_H1")
getInstrument("ES_H1.YM_H1") #synthetic

currency(c("USD","EUR"))
instrument.auto("EURUSD")
getInstrument("EURUSD") #made an exchange_rate

instrument.auto("VX_H11") #no root future defined yet!
getInstrument("VX_H11") #couldn't find future, didnt make future_series
future("VX","USD",1000,underlying_id=synthetic("SPX","USD")) #make the root
instrument.auto("VX_H11") #and try again
getInstrument("VX_H11") #made a future_series

Description

A wrapper for buildHierarchy, that defaults to returning all attributes. By default it looks for the instrument with the most attribute levels, and uses those attributes for columns. If you would prefer to use the attribute levels of a given instrument to build the columns, use attrs.of.

Usage

instrument.table(symbols = NULL, exclude = NULL, attrs.of = NULL)

Arguments

Details

if there are some attributes that you do not want to be included in the returned data.frame, specify them with exclude.

Value

data.frame

Author(s)

Garrett See

See Also

buildHierarchy, instrument

Examples

## Not run: 
currency('USD')
stock('GM','USD',exchange='NYSE')
stock('XOM','USD',description='Exxon Mobil')
instrument.table()
#Usually, currencies will not have as many attribute levels
#as other instruments, so you may want to exclude them from the table.
it <- instrument.table(exclude="USD|GM", attrs.of = "XOM") #columns created based on XOM instrument
#it <- instrument.table(exclude=c('USD','GM'), attrs.of = "XOM") #same thing
it <- instrument.table(exclude='tick_size|description|exchange')

## End(Not run)

Description

class test for object supposedly of type 'currency'

Usage

is.currency(x)

Arguments

Value

A single logical value indicating whether 'x' inherits from class '"currency"'.

check each element of a character vector to see if it is either the primary_id or an identifier of a currency

Description

check each element of a character vector to see if it is either the primary_id or an identifier of a currency

Usage

is.currency.name(x)

Arguments

Value

A logical vector indicating whether each element of 'x' identifies a defined currency instrument. Non-character input returns 'FALSE'.

Description

class test for object supposedly of type 'instrument'

Usage

is.instrument(x)

Arguments

Value

A single logical value indicating whether 'x' inherits from class '"instrument"'.

check each element of a character vector to see if it is either the primary_id or an identifier of an instrument

Description

check each element of a character vector to see if it is either the primary_id or an identifier of an instrument

Usage

is.instrument.name(x)

Arguments

Value

logical vector

Description

This function will load instrument metadata (data about the data) either from a file specified by the file argument or from a data.frame specified by the metadata argument.

Usage

load.instruments(
  file = NULL,
  ...,
  metadata = NULL,
  id_col = 1,
  default_type = "stock",
  identifier_cols = NULL,
  overwrite = TRUE
)

Arguments

Details

The function will attempt to make reasonable assumptions about what you're trying to do, but this isn't magic.

You will typically need to specify the type of instrument to be loaded, failure to do so will generate a Warning and default_type will be used.

You will need to specify a primary_id, or define a id_col that contains the data to be used as the primary_id of the instrument.

You will need to specify a currency, unless the instrument type is 'currency'

Use the identifier_cols argument to specify which fields (if any) in the CSV are to be passed to instrument as the identifiers argument

Typically, columns will exist for multiplier and tick_size.

Any other columns necessary to define the specified instrument type will also be required to avoid fatal Errors.

Additional columns will be processed, either as additional identifiers for recognized identifier names, or as custom fields. See instrument for more information on custom fields.

Value

'NULL' invisibly. Called for the side effect of creating instrument definitions in the package instrument registry.

See Also

loadInstruments, instrument, setSymbolLookup.FI, getSymbols, getSymbols.FI

Examples

example_ids <- c(
  "FI_EXAMPLE_A",
  "FI_EXAMPLE_B"
)

had_usd <- is.currency.name("USD")

tryCatch(
  {
    if (!had_usd) {
      currency("USD")
    }

    metadata <- data.frame(
      primary_id = example_ids,
      type = c("stock", "stock"),
      currency = c("USD", "USD"),
      description = c(
        "Example instrument A",
        "Example instrument B"
      ),
      stringsAsFactors = FALSE
    )

    load.instruments(metadata = metadata)

    getInstrument("FI_EXAMPLE_A")
    getInstrument("FI_EXAMPLE_B")
  },
  finally = {
    rm_instruments(example_ids)

    if (!had_usd) {
      rm_currencies("USD")
    }
  }
)

Description

Returns the names of instruments denominated in one or more specified currencies.

Usage

ls_by_currency(currency, pattern = NULL, match = TRUE, show.currencies = FALSE)

rm_by_currency(x, currency, keep.currencies = TRUE)

ls_USD(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_AUD(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_GBP(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_CAD(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_EUR(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_JPY(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_CHF(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_HKD(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_SEK(pattern = NULL, match = TRUE, show.currencies = FALSE)

ls_NZD(pattern = NULL, match = TRUE, show.currencies = FALSE)

Arguments

Value

A character vector containing instrument names denominated in the requested currencies, or 'NULL' when no matching instruments are found.

Author(s)

Garrett See

See Also

[ls_instruments()], [ls_currencies()], [rm_instruments()], [rm_currencies()], [instrument()]

Examples

example_dir <- tempfile("fi-currency-")
dir.create(example_dir)

backup_name <- "backup.RData"
backup_path <- file.path(example_dir, backup_name)

saveInstruments(backup_name, dir = example_dir)

tryCatch(
  {
    rm_instruments(keep.currencies = FALSE)

    currency(c("USD", "CAD", "GBP"))
    stock(c("CM", "CNQ"), currency = "CAD")
    stock(c("BARC", "BET"), currency = "GBP")
    stock(c("DIA", "SPY"), currency = "USD")

    ls_by_currency("CAD")
    ls_by_currency("GBP")
    ls_USD()
    ls_CAD()

    rm_by_currency(currency = "CAD")

  },
  finally = {
    if (file.exists(backup_path)) {
      reloadInstruments(
        backup_name,
        dir = example_dir
      )
    }

    unlink(example_dir, recursive = TRUE)
  }
)

Description

show names of or remove instruments that expire on a given date

Usage

ls_by_expiry(expiry, pattern = NULL, match = TRUE)

rm_by_expiry(x, expiry)

Arguments

Details

ls_by_expiry will find instruments that have a field named either “expiry” or “expires” with a value that matches expiry.

Value

ls_by_expiry gives a vector of names of instruments that expire on the given expiry. rm_by_expiry is called for its side-effect.

Author(s)

Garrett See

See Also

ls_instruments, ls_options, ls_calls, ls_puts, ls_futures, ls_derivatives

Examples

## Not run: 
ls_by_expiry('20110917')
ls_by_expiry('20110917',ls_options())

## End(Not run)

Description

show unique expiration dates of instruments

Usage

ls_expiries(
  pattern = NULL,
  match = TRUE,
  underlying_id = NULL,
  type = "derivative"
)

ls_expires(
  pattern = NULL,
  match = TRUE,
  underlying_id = NULL,
  type = "derivative"
)

Arguments

Details

ls_expires is an alias. (plural of expires?)

type is currently only implemented for ‘derivative’, ‘future’, ‘option’, ‘call’ and ‘put’ internally, a call is made to the appropriate ls_ function.

Value

named chr vector with length of unique expiration dates of derivatives of class type and having an underlying_id of underlying_id if given.

Note

This should be updated to deal with dates instead of character strings

Author(s)

Garrett

See Also

ls_instruments_by for things like e.g. ls_instruments_by('expires','20110916'), ls_instruments, ls_derivatives, ls_options, ls_calls, buildHierarchy, instrument.table

Examples

## Not run: 
option_series.yahoo('SPY')
option_series.yahoo('DIA',NULL)
ls_expiries()


## End(Not run)

Description

display the names of or delete instruments, stocks, options, futures, currencies, bonds, funds, spreads, guaranteed_spreads, synthetics, derivatives, or non-derivatives.

Usage

ls_instruments(pattern = NULL, match = TRUE, verbose = TRUE)

ls_stocks(pattern = NULL, match = TRUE)

ls_options(pattern = NULL, match = TRUE, include.series = TRUE)

ls_option_series(pattern = NULL, match = TRUE)

ls_futures(pattern = NULL, match = TRUE, include.series = TRUE)

ls_future_series(pattern = NULL, match = TRUE)

ls_currencies(pattern = NULL, match = TRUE, includeFX = FALSE)

ls_non_currencies(pattern = NULL, match = TRUE, includeFX = TRUE)

ls_exchange_rates(pattern = NULL, match = TRUE)

ls_FX(pattern = NULL, match = TRUE)

ls_bonds(pattern = NULL, match = TRUE)

ls_funds(pattern = NULL, match = TRUE)

ls_spreads(pattern = NULL, match = TRUE)

ls_guaranteed_spreads(pattern = NULL, match = TRUE)

ls_synthetics(pattern = NULL, match = TRUE)

ls_ICS(pattern = NULL, match = TRUE)

ls_ICS_roots(pattern = NULL, match = TRUE)

ls_derivatives(pattern = NULL, match = TRUE)

ls_non_derivatives(pattern = NULL, match = TRUE)

ls_calls(pattern = NULL, match = TRUE)

ls_puts(pattern = NULL, match = TRUE)

rm_instruments(x, keep.currencies = TRUE)

rm_stocks(x)

rm_options(x)

rm_option_series(x)

rm_futures(x)

rm_future_series(x)

rm_currencies(x)

rm_exchange_rates(x)

rm_FX(x)

rm_bonds(x)

rm_funds(x)

rm_spreads(x)

rm_synthetics(x)

rm_derivatives(x)

rm_non_derivatives(x, keep.currencies = TRUE)

Arguments

Details

ls functions return the names of all the instruments of the class implied by the function name. rm functions remove the instruments of the class implied by the function name

rm_instruments and rm_non_derivatives will not delete currencies unless the keep.currencies argument is FALSE.

For the rm functions, x can be a vector of instrument names, or nothing. If x is missing, all instruments of the relevant type will be removed.

It can be useful to nest these functions to get things like futures denominated in USD.

Value

ls functions return vector of character strings corresponding to instruments of requested type rm functions are called for side-effect

Author(s)

Garrett See

See Also

ls_instruments_by, ls_by_currency, ls_by_expiry, ls, rm, instrument, stock, future, option, currency, FinancialInstrument::sort_ids

Examples

rm_instruments(keep.currencies=FALSE) #remove everything from .instrument

# First, create some instruments
currency(c("USD", "EUR", "JPY"))
#stocks
stock(c("S", "SE", "SEE", "SPY"), 'USD')
synthetic("SPX", "USD", src=list(src='yahoo', name='^GSPC'))
#derivatives
option('.SPY', 'USD', multiplier=100, underlying_id='SPY')
option_series(root_id="SPY", expires='2011-06-18', callput='put', strike=130)
option_series(root_id="SPY", expires='2011-09-17', callput='put', strike=130)
option_series(root_id="SPY", expires='2011-06-18', callput='call', strike=130)
future('ES', 'USD', multiplier=50, expires='2011-09-16', underlying_id="SPX")
option('.ES','USD',multiplier=1, expires='2011-06',strike=1350, right='C', underlying_id='ES')

# Now, the examples
ls_instruments() #all instruments
ls_instruments("SE") #only the one stock
ls_instruments("S", match=FALSE) #anything with "S" in name

ls_currencies()
ls_stocks()
ls_options()
ls_futures()
ls_derivatives()
ls_puts()
ls_non_derivatives()
ls_by_expiry('20110618',ls_puts()) #put options that expire on Jun 18th, 2011
ls_puts(ls_by_expiry('20110618'))

rm_options('SPY_110618C130')
rm_futures()
ls_instruments()
rm_instruments('EUR', keep.currencies=FALSE) #remove the currency
rm_currencies('JPY') #or remove currency like this
ls_currencies()
ls_instruments()

rm_instruments() #remove all but currencies
rm_currencies()

Description

list names of instruments that have an attribute that matches some value

Usage

ls_instruments_by(what, value, in.slot = NULL, pattern = NULL, match = TRUE)

Arguments

Details

list instruments that have a given attribute level with a given value.

Value

chr vector of instrument names

Author(s)

Garrett See

See Also

buildHierarchy, instrument.table, ls_instruments

Examples

## Not run: 
stock(c("GOOG","INTC"),currency("USD"))
synthetic("SnP","USD",src=list(name='^GSPC',src='yahoo'))
ls_instruments_by('type','stock')
ls_instruments_by("name",NULL,in.slot='src')
ls_instruments_by('src',NULL)

## End(Not run)

Description

list the strike prices of previously defined options.

Usage

ls_strikes(pattern = NULL)

Arguments

Details

If no option names are supplied, the strike prices of all defined options will be returned

Value

vector of strike prices

Author(s)

Garrett See

See Also

ls_options, ls_calls, ls_puts ls_instruments_by ls_underlyings

Examples

## Not run: 
option_series.yahoo('SPY')
ls_strikes(ls_options('SPY'))

## End(Not run)

Description

shows names that are stored in the underlying_id slot of derivative instruments

Usage

ls_underlyings(pattern = NULL, match = TRUE)

Arguments

Details

first calls ls_derivatives, then looks for unique underlying_ids. If no derivatives have been defined, nothing will be returned.

Value

chr vector of names of unique underlying_ids

Author(s)

Garrett See

See Also

ls_instruments_by, ls_derivatives, ls_options, ls_futures

Examples

## Not run: 
ls_underlyings()

## End(Not run)

Description

Construct a primary_id for a spread instrument from the primary_ids of its members

Usage

make_spread_id(x, root = NULL, format = NULL, sep = "_")

Arguments

Value

character string that can be used as a primary_id for a spread instrument

Author(s)

Garrett See

See Also

spread, build_spread_symbols, build_series_symbols

Examples

ids <- c('VX_aug1','VX_U11')
make_spread_id(ids, format='CY')
make_spread_id(ids, format=FALSE)
make_spread_id(c("VIX_JAN11","VIX_FEB11"),root='VX',format='CY')

Description

This will convert month codes or month names to numeric months.

Usage

month_cycle2numeric(...)

MC2N(...)

Arguments

Details

Input can be a vector, comma-delimited string, or multiple strings. All inputs should be similar. Do not mix month names, codes and numbers in the same call.

MC2N is an alias

Value

numeric vector

Author(s)

Garrett See

See Also

M2C, C2M, next.future_id future

Examples

MC2N("H,M,U,Z") # from single string
MC2N(c("H","M","U","Z")) # from single vector
MC2N("h", "M", "u", "Z") # from multiple strings
MC2N(c("F","G"), "H", c("X","Z")) # from multiple vectors
month_cycle2numeric("Mar,jun,SEP,dEc") 
month_cycle2numeric("Mar", "jun", "SEP", "dEc")
MC2N("March,june,sep,decem")
MC2N("March, june, sep, decem") #spaces between commas are ok
month_cycle2numeric("3,6,9,12")
month_cycle2numeric(seq(3,12,3))

Description

Using parse_id, this will figure out where in the month_cycle that id belongs. Then, it will use the next (previous) month in month_cycle to construct the id of the next-to-expire contract.

Usage

next.future_id(id, month_cycle = seq(3, 12, 3), root = NULL, format = NULL)

prev.future_id(id, month_cycle = seq(3, 12, 3), root = NULL, format = NULL)

Arguments

Details

month_cycle can be a numeric vector (corresponding to the months in which contracts expire), or it can be a vector of month codes, a vector of month abbreviations, or a comma-delimited string of month codes or abbreviations, in which case an attempt will be made to convert it to a numeric vector. by passing it through month_cycle2numeric

root is primarily used when you have an id that does not have an underscore, in which case, providing root will make splitting the id into primary_id and suffix_id easier and more accurate. root can also be used if you want the returned id to be on a different future than the id you passed in (when used this way, format should also be used).

By default, (when called with format=NULL) the returned id will be of the same format as the id that was passed in. The format of the returned id can be specified with the format argument. See format_id for supported values of format

Value

character

Author(s)

Garrett See

See Also

format_id for supported values of format. month_cycle2numeric

Examples

next.future_id("ES_Z1","H,M,U,Z", format=NULL) 
next.future_id("VIXAUG11", 1:12, root='VIX', format=NULL)
next.future_id("YM_Q11", seq(3,12,3)) #gives a warning about 'Q' not being part of month_cycle

Description

Notionalize multiplies all prices by the contract multiplier Denotionalize divides all prices by the contract multiplier

Usage

Notionalize(x, name, env = .GlobalEnv)

Denotionalize(x, name, env = .GlobalEnv)

Arguments

Details

The mulitplier is only applied to columns with prices. A column is considered to be a price column if its name contains “Open”, “High”, “Low”, “Close”, “Bid”, “Ask”, “Trade”, “Mid”, or “Price” and does not contain “Size”, “Sz”, “Volume”, “Qty”, “Quantity”, “OpInt”, “OpenInterest” (not case-sensitive)

Value

an object of the same class as x

Author(s)

Garrett See

Examples

## Not run: 
source("http://tinyurl.com/download-tblox")
getSymbols("CL", src='tblox')
define_futures.tblox()
tail(Notionalize(CL, "CL"))
tail(Denotionalize(Notionalize(CL), "CL"))

## End(Not run)

Description

Defines a chain or several chains of options by looking up necessary info from yahoo.

Usage

option_series.yahoo(
  symbol,
  Exp,
  currency = "USD",
  multiplier = 100,
  first_traded = NULL,
  tick_size = NULL,
  overwrite = TRUE
)

Arguments

Details

If Exp is missing it will define only the nearby options. If Exp is NULL it will define all options

If first_traded and/or tick_size should not be the same for all options being defined, they should be left NULL and defined outside of this function.

Value

Called for side-effect. The instrument that is created and stored will inherit option_series, option, and instrument classes.

Note

Has only been tested with stock options. The options' currency should be the same as the underlying's.

Author(s)

Garrett See

References

Yahoo Finance at "finance.yahoo.com"

See Also

option_series, option, instrument, getOptionChain

Examples

option_series.yahoo('SPY') #only nearby calls and puts
option_series.yahoo('DIA', Exp=NULL) #all chains
ls_instruments()

Description

Extract/infer descriptive information about an instrument from its name.

Usage

parse_id(x, silent = TRUE, root = NULL)

Arguments

Details

This function is primarily intended to be used on the names of future_series and option_series instruments, and it will work best if the id has an underscore in it that separates the root_id from the suffix_id. (However, it should be able to handle most ids even if the underscore is missing). After splitting x into a root_id and suffix_id, the suffix_id is passed to parse_suffix (see also) for further processing.

TODO: add support for bond_series.

Value

a list of class ‘id.list’ containing ‘root’ and ‘suffix’ as well as what is returned from parse_suffix (type, month, year, strike, right, cm, cc, format)

Note

this function will identify x as an exchange_rate only if it is 6 characters long and made up of 2 previously defined currency instruments.

Author(s)

Garrett See

See Also

parse_suffix

Examples

parse_id("ES_Z11")
parse_id("CLZ1")
parse_id("SPY_111217C130")

Description

extract information from the suffix_id of an instrument

Usage

parse_suffix(x, silent = TRUE)

Arguments

Details

These would be recognized as a Sep 2011 outright futures contract: U1, U11, SEP1, SEP11, U2011, Sep2011, SEP2011

These would be recognized as a call with a strike of 122.5 that expires Sep 17, 2011: 110917C122.5, 20110917C122.5, 110917C00122500, 20110917C00122500

These would be recognized as Sep 2011 single stock futures: 1CU1, 1CU11, 1CSEP11, 1DU1 (dividend protected)

These would be recognized as Adjusted futures: cm.30 (30 day constant maturity future), cc.OI (continuous contract rolled when Open Interest rolls), cc.Vol (continuous contract roll when Volumn rolls), cc.Exp.1 (continuous contract rolled 1 day before Expiration)

Synthetics and spreads:

SPY.DIA –> type == synthetic;

U1.Z1 or U11.Z11 –> type == "calendar", "spread"; month == 'SEP', year == 2011

U1.0302 –> type == "ICS", "spread"; month == 'SEP', year == 2011

110917C125.110917P125 –> type == option_spread, spread

Value

an object of class ‘suffix.list’ which is a list containing ‘type’ of instrument, ‘month’ of expiration, ‘year’ of expiration, ‘strike’ price of option, ‘right’ of option (“C” or “P”), ‘cm’ (maturity in days of a constant maturity contract), ‘cc’ (method for calculating a continuous contract), ‘format’ (string that indicates the format of the unparsed id).

Author(s)

Garrett See

See Also

parse_id, format_id

Examples

parse_suffix("U11")
parse_suffix("110917C125")

Description

Redenominate (change the base of) an instrument

Usage

redenominate(
  x,
  new_base = "USD",
  old_base = NULL,
  EOD_time = "15:00:00",
  env = .GlobalEnv,
  silent = FALSE
)

Arguments

Details

If old_base is not provided, x must be the name of an instrument (or an object with the name of a defined instrument) so that the currency attribute of the instrument can be used. Otherwise, old_base must be provided.

If you want to convert to JPY something that is denominated in EUR, you must have data for the EURJPY (or JPYEUR) exchange rate. If you don't have data for EURJPY, but you do have data for EURUSD and USDJPY, you could redenominate to USD, then redenominate to EUR, but this function is not yet smart enough to do that for you.

See the help for buildRatio also.

Value

xts object, with as many columns as practicable, that represents the value of an instrument in a different currency (base).

Note

this does not yet define any instruments or assign anything.

Author(s)

Garrett See

See Also

buildRatio

Examples

## Not run: 
require(quantmod)
EURUSD <- getSymbols("EURUSD=x",src='yahoo',auto.assign=FALSE)
GLD <- getSymbols("GLD", src='yahoo', auto.assign=FALSE)
GLD.EUR <- redenominate(GLD,"EUR","USD") #can call with xts object

currency("USD")
stock("GLD","USD")
GLD.EUR <- redenominate('GLD','EUR') #can also call with instrument name

## End(Not run)

future metadata to be used by load.instruments

Description

future metadata to be used by load.instruments

Description

Saves (loads) the .instrument environment to (from) disk.

Usage

saveInstruments(file_name = "MyInstruments", dir = "", compress = "gzip")

loadInstruments(file_name = "MyInstruments", dir = "")

reloadInstruments(file_name = "MyInstruments", dir = "")

Arguments

Details

After you have defined some instruments, you can use saveInstruments to save the entire .instrument environment to disk.

loadInstruments will read a file that contains instruments and add those instrument definitions to your .instrument environment. reloadInstruments will remove all instruments in the current .instrument environment before loading instruments from disk.

The file_name should have a file extension of “RData”, “rda”, “R”, or “txt”. If the file_name does not end with one of those, “.RData” will be appended to the file_name

If the file extension is “R” or “txt”, saveInstruments will create a text file of R code that can be sourced to load instruments back into the .instrument environment.

Value

Called for side-effect

Author(s)

Garrett See

See Also

save, load load.instrument define_stocks, define_futures, define_options (option_series.yahoo)

Examples

backup_file <- tempfile(fileext = ".RData")
output_dir <- tempfile("fi-save-test-")
dir.create(output_dir)

saveInstruments(backup_file)

tryCatch(
  {
    rm_instruments(keep.currencies = FALSE)

    currency("USD")
    stock("SPY", currency = "USD")

    saveInstruments(
      "test-instruments.R",
      dir = output_dir
    )

    rm_instruments(keep.currencies = FALSE)

    source(
      file.path(output_dir, "test-instruments.R")
    )

    stopifnot(is.instrument.name("SPY"))
    stopifnot(getInstrument("SPY")$currency == "USD")
  },
  finally = {
    reloadInstruments(backup_file)
    unlink(backup_file)
    unlink(output_dir, recursive = TRUE)
  }
)

Description

Save data to disk the way that getSymbols.FI expects it to be saved.

Usage

saveSymbols.days(Symbols, base_dir = "", extension = "rda", env = .GlobalEnv)

saveSymbols.common(Symbols, base_dir = "", extension = "rda", env = .GlobalEnv)

Arguments

Details

If they do not already exist, subdirectories will be created for each of the Symbols. saveSymbols.common will save a single ‘rda’ file for each of the Symbols in that symbol's subdirectory. saveSymbols.days will split the data up into days and save a separate ‘rda’ file for each day in that symbol's subdirectory.

Value

called for side-effect.

See Also

getSymbols.FI

Examples

example_dir <- tempfile("fi-symbol-data-")
dir.create(example_dir)

example_env <- new.env()

example_env$SPY <- xts::xts(
  matrix(
    1:8,
    ncol = 2L,
    dimnames = list(
      NULL,
      c("Close", "Volume")
    )
  ),
  order.by = as.Date("2020-01-01") + 0:3
)

tryCatch(
  {
    saveSymbols.common(
      "SPY",
      base_dir = example_dir,
      env = example_env
    )

    list.files(
      example_dir,
      recursive = TRUE
    )
  },
  finally = {
    unlink(example_dir, recursive = TRUE)
  }
)

Description

This function exists to tell getSymbols where to look for your repository of market data.

Usage

setSymbolLookup.FI(
  base_dir,
  Symbols,
  ...,
  split_method = c("days", "common"),
  storage_method = "rda",
  use_identifier = "primary_id",
  extension = "rda",
  src = "FI"
)

Arguments

Details

The base_dir parameter must be set or the function will fail. This will vary by your local environment and operating system. For mixed-OS environments, we recommend doing some OS-detection and setting the network share to your data to a common location by operating system. For example, all Windows machines may use “M:/” and all *nix-style (linux, Mac) machines may use “/mnt/mktdata/”.

The split_method currently allows either ‘days’ or ‘common’, and expects the file or files to be in sub-directories named for the symbol. In high frequency data, it is standard practice to split the data by days, which is why that option is the default.

Value

No meaningful return value. Called for the side effect of updating the 'quantmod' symbol lookup table for the requested instruments.

See Also

getSymbols.FI, instrument_attr, load.instruments, loadInstruments, setSymbolLookup

Description

Primarily intended for use on the primary_ids of future_series instruments. This will sort ids by expiration. All ids that do not contain month and year information will be sorted alphabetically (separately) and appended to the end of the other sorted ids.

Usage

sort_ids(ids, ...)

Arguments

Details

If an instrument is defined, and has a date in its ‘expires’ field, that date will be used as the expiration date. Otherwise, it is assumed that the contract expires on the first day of its expiration month. This means that if some products are defined and other products that expire in the same month are not defined, the ones that are not defined will come first in the vector of sorted ids.

Value

sorted character vector of the same length as ids

Author(s)

Garrett See

See Also

parse_id

Examples

## Not run: 
ids <- c("ES_U11",'GLD','SPY',"YM_Jun11",'DIA','VX_V10')
sort_ids(ids)

## End(Not run)

Description

define spreads, guaranteed_spreads, butterflies, and other synthetic instruments

Usage

synthetic(
  primary_id = NULL,
  currency = NULL,
  multiplier = 1,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  ...,
  members = NULL,
  type = "synthetic"
)

synthetic.instrument(
  primary_id,
  currency,
  members,
  memberratio,
  ...,
  multiplier = 1,
  tick_size = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  type = c("synthetic.instrument", "synthetic")
)

spread(
  primary_id = NULL,
  currency = NULL,
  members,
  memberratio,
  tick_size = NULL,
  ...,
  multiplier = 1,
  identifiers = NULL,
  assign_i = TRUE
)

butterfly(
  primary_id = NULL,
  currency = NULL,
  members,
  tick_size = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  ...
)

guaranteed_spread(
  primary_id = NULL,
  currency = NULL,
  root_id = NULL,
  suffix_id = NULL,
  members = NULL,
  memberratio = c(1, -1),
  ...,
  multiplier = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  tick_size = NULL
)

ICS_root(
  primary_id,
  currency = NULL,
  members,
  multiplier = NULL,
  identifiers = NULL,
  assign_i = TRUE,
  overwrite = TRUE,
  tick_size = NULL,
  ...
)

ICS(primary_id, assign_i = TRUE, identifiers = NULL, ...)

Arguments

Details

Simple derivatives like option or future contracts typically have one underlying instrument. While properties like strike and expiration vary for these derivative contracts or series, the underlying is well understood.

More complex derivatives are typically modeled as baskets of underlying products, and are typically traded over-the-counter or as proprietary in-house products.

The general synthetic function is intended to be extended to support these arbitrary baskets of assets.

spread guaranteed_spread and butterfly are wrappers for synthetic.instrument. synthetic.instrument will make a call to synthetic to create the final instrument.

The suffix_id parameter of wrapper functions such as guaranteed_spread is presumed to be a string describing the members. It will be strsplit using the regex "[-;:_,\.]" to create the members vector, and potentially combined with a root_id.

Most wrappers will build primary_id if it is NULL, either by combining root_id and suffix_id, or by passing members in a call to make_spread_id

ICS will build an Intercommodity Spread. Although the expiration date and ratio may change, the members of a given ICS will not change. Therefore, ICS_root can be used to hold the members of an Intercommodity Spread. If an ICS_root has not been defined, then members will be a required argument for ICS

We welcome assistance from others to model more complex OTC derivatives such as swap products.

Value

called for side effect. stores an instrument in .instrument environment

Author(s)

Brian Peterson, Garrett See

See Also

instrument, future, option_series.yahoo

Examples

## Not run: 
stock('SPY','USD',1)
stock('DIA','USD',1)
spread('SPY.DIA','USD',c('SPY','DIA'),c(1,-1))

## End(Not run)

Description

This is like taking a snapshot of the market at the end of every second, except the volume over the second is summed.

Usage

to_secBATV(x)

alltick2sec(
  getdir = getOption("FinancialInstrument.tickdir", NULL),
  savedir = getOption("FinancialInstrument.secdir", NULL),
  Symbols = NULL,
  overwrite = FALSE,
  verbose = FALSE
)

Arguments

Details

From tick data with columns: “Price”, “Volume”, “Bid.Price”, “Bid.Size”, “Ask.Price”, “Ask.Size”, to data of one second frequency with columns “Bid.Price”, “Bid.Size”, “Ask.Price”, “Ask.Size”, “Trade.Price”, and “Volume”

The primary purpose of these functions is to reduce the amount of data on disk so that it will take less time to load the data into memory.

If there are no trades or bid/ask price updates in a given second, we will not make a row for that timestamp. If there were no trades, but the bid or ask price changed, then we _will_ have a row but the Volume and Trade.Price will be NA.

If there are multiple trades in the same second, Volume will be the sum of the volume, but only the last trade price in that second will be printed. Similarly, if there is a trade, and then later in the same second, there is a bid/ask update, the last Bid/Ask Price/Size will be used.

alltick2sec is used to convert the data of several files from tick to one second frequency data.

Value

to_secBATV returns an xts object of one second frequency. alltick2sec returns a list of files that were converted.

Note

to_secBATV is used by the TRTH_BackFill.R script in the inst/parser directory of the FinancialInstrument package. These functions are specific to to data created by that script and are not intended for more general use.

Author(s)

gsee

Examples

## Not run: 
getSymbols("CLU1")
system.time(xsec <- to_secBATV(CLU1))
convert.log <- alltick2sec(
  getdir = "path/to/tick-data",
  savedir = "path/to/second-data",
  verbose = TRUE
)

## End(Not run)

Description

Update instruments with metadata from another instrument.

Usage

update_instruments.instrument(
  Symbols,
  source_id,
  create.new = FALSE,
  ignore = "identifiers",
  assign_i = TRUE
)

Arguments

Details

By default, only attributes that have a value of "" will be given a new value.

If create.new is TRUE, then if there are attributes in source_id that are not in the Symbols' instrument, those attributes will be copied to the updated instruments unless they are in ignore.

Value

if isTRUE(assign_i) a vector of primary_ids of the instruments that were upated. Otherwise, a list of updated instrument objects.

Note

one way to overwrite attributes of one instrument with those of another is to first set equal to "" those attributes that you want to overwrite, then use update_instruments.instrument to copy the attributes.

Author(s)

Garrett See

See Also

update_instruments.yahoo, all.equal.instrument

Examples

## Not run: 
#rm_instruments()
currency("USD")
synthetic("SPX", "USD", identifiers=list(yahoo="GSPC"),
          tick_size=0.01,
         liquidHours="T08:30:00/T15:00:00",
         extraField='something else',
         assign_i=TRUE)
stock("SPY", "USD", liquidHours="", assign_i=TRUE)
all.equal(getInstrument("SPX"), getInstrument("SPY"))
getInstrument("SPY")
## update SPY metadata based on the metadata of SPX
## Only attributes that == "" are updated by default
update_instruments.instrument("SPY", "SPX", assign_i=FALSE) #liquidHours
update_instruments.instrument("SPY", "SPX", create.new=TRUE,
                              ignore=c("identifiers", "type"),
                              assign_i=FALSE)
# Although you probably do NOT want to, this will
# copy everything new -- including identifiers and type!
update_instruments.instrument("SPY", "SPX", create.new=TRUE, ignore=NULL,
                              assign_i=FALSE)

## End(Not run)

Description

This will update previously defined iShares or SPDR ETF instruments. Both functions will add attributes for “Name”, and “FundFamily” (“iShares” or “SPDR”). update_instruments.iShares will also add an attribute for “MgmtFees”

Usage

update_instruments.iShares(Symbols, silent = FALSE)

update_instruments.SPDR(Symbols, silent = FALSE)

Arguments

Value

called for side-effect

Note

update_instruments.SPDR will probably NOT work on Windows because in the call to download.file it uses method=curl since it has to download from an https URL scheme.

Author(s)

Garrett See

References

http://us.ishares.com/home.htm, https://www.ssga.com/de/en_gb/intermediary

See Also

update_instruments.yahoo, update_instruments.TTR, twsInstrument:::update_instruments.IB, update_instruments.instrument, update_instruments.morningstar, update_instruments.masterDATA

Examples

## Not run: 
stock("IWC", currency("USD"))
update_instruments.iShares("IWC")
getInstrument("IWC")

Symbols <- stock(c("SPY", "JNK"), currency("USD"))
update_instruments.SPDR(Symbols)
buildHierarchy(c("SPY", "JNK"), "Name")

## End(Not run)

Description

Uses the masterDATA.com list of ETFs and ETNs to update previously defined instruments.

Usage

update_instruments.masterDATA(Symbols, silent = FALSE)

update_instruments.md(Symbols, silent = FALSE)

Arguments

Details

update_instruments.md is an alias.

MasterDATA classifies each ETF into one of six Fund.Types. From their website:

US Equity ETF: All constituents trade on a US exchange. Both ProShares and Rydex sponsor ETFs with the objective of achieving the performance (or a multiple of the performance) of several major US stock indexes. These ETFs currently are included in this category despite the fact that their constituent lists are generally not limited to US stocks.

Global Equity ETF: One or more of the constituents do not trade on a US Exchange.

Fixed Income ETF: The constituent list contains government and / or corporate debt instruments. ETFs with this classification will not be considered for inclusion in MasterDATA's index / ETF compilation list.

Commodity Based ETF: This classification of ETF has no constituents but is structured to reflect the valuation of a commodity such as gold, silver, oil or interest rates. ETFs with this classification will not be considered for inclusion in MasterDATA's index / ETF compilation list.

Exchange Traded Notes: A type of unsecured, unsubordinated debt security that was first issued by Barclays Bank PLC. The purpose of ETNs is to create a type of security that combines both the aspects of bonds and exchange traded funds (ETF). Similar to ETFs, ETNs are traded on a major exchange.

Value

called for side-effect. Each ETF that is updated will be given instrument attributes of “Name” and “Fund.Type”

Author(s)

Garrett See

References

http://masterDATA.com (http://www.masterdata.com/helpfiles/ETF_List_Downloads/AllTypes.csv)

See Also

update_instruments.yahoo, update_instruments.instrument

Examples

## Not run: 
stock(s <- c("SPY", "DIA"), currency("USD"))
update_instruments.masterDATA(s)
buildHierarchy(s, "Name", "Fund.Type", "defined.by")

## End(Not run)

Description

Currently, this only updates ETFs. It will add “msName” and “msCategory” attributes to the instruments. (ms for morningstar)

Usage

update_instruments.morningstar(Symbols, silent = FALSE)

update_instruments.ms(Symbols, silent = FALSE)

Arguments

Value

called for side-effect.

Author(s)

Garrett See

References

http://www.morningstar.com

See Also

update_instruments.yahoo, update_instruments.TTR update_instruments.iShares

Description

Adds/updates information in instrument with data downloaded from yahoo

Usage

update_instruments.yahoo(Symbols = c("stocks", "all"), verbose = FALSE)

update_instruments.TTR(
  Symbols = c("stocks", "all"),
  exchange = c("AMEX", "NASDAQ", "NYSE"),
  silent = FALSE
)

Arguments

Details

Although these functions are intended to update the metadata of previously defined instruments, update_instruments.TTR will define the stocks if they do not already exist.

update_instruments.TTR is only to be used on U.S. stocks denominated in USD.

Value

called for side-effect

Author(s)

Garrett See

References

Yahoo! Finance "finance.yahoo.com" and YahooQuote

See Also

update_instruments.instrument, update_instruments.morningstar, update_instruments.masterDATA, stockSymbols, stock

Examples

## Not run: 
	stock('GS',currency('USD'))
 update_instruments.yahoo('GS')
	getInstrument('GS')
 update_instruments.TTR('GS')
 getInstrument('GS')

## End(Not run)

Description

generate endpoints for volume bars

Usage

volep(x, units)

Arguments

Value

An integer vector containing row positions where cumulative volume crosses successive multiples of 'units'. These positions may be used as endpoints for constructing volume bars.

Author(s)

Joshua Ulrich