load.instruments: Load instrument metadata into the .instrument environment

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
)

Value

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

Arguments

file: string identifying file to load, default NULL, see Details
...: any other passthru parameters
metadata: optional, data.frame containing metadata, default NULL, see Details
id_col: numeric column containing id if primary_id isn't defined, default 1
default_type: character string to use as instrument type fallback, see Details
identifier_cols: character vector of field names to be passed as identifiers, see Details
overwrite: TRUE/FALSE. See instrument.

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.

Examples

Run this code

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")
    }
  }
)