instrument {FinancialInstrument}

instrument class constructors

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

primary_id

String describing the unique ID for the instrument. Most of the wrappers allow this to be a vector.

...

Any other passthru parameters, including

currency

String describing the currency ID of an object of type currency

multiplier

Numeric multiplier to apply to the price in the instrument to get to notional value.

tick_size

The tick increment of the instrument price in it's trading venue, as numeric quantity (e.g. 1/8 is .125)

identifiers

Named list of any other identifiers that should also be stored for this instrument

type

instrument type to be appended to the class definition, typically not set by user

assign_i

TRUE/FALSE. Should the instrument be assigned to the .instrument environment? Default is FALSE for instrument, TRUE for wrappers.

overwrite

TRUE/FALSE. Should existing instruments with the same primary_id be overwritten? Default is TRUE. If FALSE, an error will be thrown and the instrument will not be created.

underlying_id

For derivatives, the identifier of the instrument that this one is derived from, may be NULL for cash settled instruments

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.

See Also

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