Package {alphavantagepf}

alphavantagepf: A lightweight R interface to the Alpha Vantage API

Description

An R interface to the Alpha Vantage API which emphasizes normalized data nd data.table conventions

Details

The alphavantagepf package provides a lightweight interface to the Alpha Vantage API. Alpha Vantage is a free source for financial data that in many cases is more accurate than Yahoo Finance and Google Finance. Get a free API KEY at https://www.alphavantage.co. Then use the R interface functions avpf_api_key("YOUR_KEY") to set the API key and the av_get_pf() function to get financial data.

av_add_analytic

Description

Adds a user-defined function to the av Shiny app

Usage

av_add_analytic(runcode, func_name, helpstr = "user function", focus = "MAIN")

Arguments

Details

Adds or removes a new command to the av_runShiny app

When the av_runShiny() app is run, users can call functions to provide analytics based on asset strings in the command line. This function allows users to add their own analytics by registering a function which takes, as inputs

1. todo: The command line and any subsequent parameters as a space delimited string

2. rv: Reactive values supplied by the Shiny app. In particular the parameter rv$istr1 contains the semicolon delimited set of assets prior to the command invocation. The registered function should return a (possibly named, see vignette) list containing one or more gt() tables, dygraphs(), or ggplots() to be displayed when the command is run. See vignette for specfic details

• The function specified must be available (i.e in .GlobalENv()) to the Shiny app when the command is run. Otherwise an error message will be displayed.

• If the specified command has already been registered, a message will be given and the internal data will be overridden.

Value

String message with success or failure of function addition.

See Also

av_runShiny()

Examples

## Not run: 
my_testfunc <- function(todo,rv) {
  message("todO: ",todo," with asset string ",rv$istr1)
  n_to_return <- c(strsplit(todo," "),"3")[[2]] |> as.numeric()
  table1 <- head(mtcars,n_to_return) |> gt()
  table2 <- data.table(asset=strsplit(rv$istr1,";")) |> gt()
  plot1 <- ggplot(mtcars,aes(mpg,disp)) + geom_point()
  return(list(table1, table2, plot1))
}
av_add_analytic("TEST","my_testfunc",helpstr="a test func")
# From the app; run "QQQ;SPY test 5"
# From the app: run "av.h"

## End(Not run)

Add asset lists

Description

Adds asset lists to av_runShiny() internal data.

Usage

av_add_assetgroups(indta)

Arguments

Details

Add Asset Groups

Lists are specified in normalized form. Duplicate list names with those currently in use are replaced.

Value

Nothing

See Also

av_runShiny()

Examples

## Not run: 
newtickers <- c("QQQ","QQQE","NDX")
av_add_assetgroups(data.table(listnm=rep("nasdaq",length(newtickers)),ticker=newtickers))
# To remove an asset list, just use an empty string for the ticker
av_add_assetgroups(data.table(listnm=c("new"),ticker=c("")))

## End(Not run)

Add or download Earnings Data

Description

Adds earnings data to av_runShiny() internal data, either by download or with user data

Usage

av_add_earn(
  substitute_earn = NULL,
  substitute_earnest = NULL,
  equitylist = NULL,
  delay = 0
)

Arguments

Details

Add Earnings Data

Entire set of columns from av_get_pf() can be added. First date column renamed to timestamp. If just assetypes is given, the function downloads earnings as needed (respecting maximum age parameters defined in the app's AVOPTS tab.) Note that price data must always be added first

Value

Data.table with summary of downloaded or added earnings

See Also

av_runShiny()

Examples

## Not run: 
# To add earnings for a set of tickers
av_load_shinydata()  # Make sure most recent data is loaded
av_add_earn(equitylist=data.table(symbol=c("IBM","GS")))

## End(Not run)

Add or download Price or Time Series Data

Description

Adds price data to av_runShiny() internal data.

Usage

av_add_px(
  indta = NULL,
  assettypes = NULL,
  equitylist = NULL,
  dtstr = "-30y::",
  delay = 0
)

Arguments

Details

Add Price or Time Series Data

Entire set of columns from av_get_pf() can be added. First date column renamed to timestamp internally.

Value

Nothing

See Also

av_runShiny()

Examples

## Not run: 
# To add known symbols outside the app
av_load_shinydata()  # Make sure most recent data is loaded
av_add_px(equitylist=c("IBM","GS","JPM"))

# To add ad-hoc data from Alphavantage (e.g. Natgas spot at Henry Hub)
# Note that "symbol" in indta must match same in assettypes
asset_df <- data.frame(symbol=c("GAS_HH"),type=c("user"),currency=c("USD"), name=c("GAS_HH"))
ng_data <- av_get_pf("","NATURAL_GAS")[,.(symbol="GAS_HH",timestamp,close=value)]
av_add_px(ng_data, assettypes=asset_df)

# To data from other sources
suppressMessages(require(quantmod))
ffdta <- as.data.table(quantmod::getSymbols("FEDFUNDS",src="FRED",auto.assign=FALSE))
ffdta <- ffdta[,.(DT_ENTRY=index,close=FEDFUNDS,adjusted_close=FEDFUNDS,symbol="FEDFUNDS")]
av_add_px(ffdta)

## End(Not run)

Extract data from AlphaVantage API results

Description

av_extract_df() pulls out nested data.frames from mixed data returned by av_get_pf() av_extract_fx() returns a simplified FX quote in data.table formfrom av_get_pf() calls. av_extract_analytics() returns melted data.table from calls to av_get_pf("ANALYTICS_FIXED_WINDOW") or av_get_pf("ANALYTICS_SLIDING_WINDOW") av_extract_divs_or_splits() returns melted data.table from calls to av_get_pf("DIVIDENDS") or av_get_pf("SPLITS")

Usage

av_extract_df(indta, grepstring = "", melt = FALSE, empty_dt_onerror = TRUE)

av_extract_fx(indta, outputform = "common", cols = "", empty_dt_onerror = TRUE)

av_extract_analytics(indta, separate_vars = FALSE, empty_dt_onerror = TRUE)

av_extract_divs_or_splits(indta, empty_dt_onerror = TRUE)

Arguments

Details

av_get_pf() frequently returns a nested data.table, or a structure with nested data.frames. These are utilities functions to extract, filter and summarize returned values. if av_get_pf() returns a valid response, but empty extracted data.tables, am empty data.table() will be returned NOTE: (Change 20260724: Timestamp is returned in POSIXct form in local Sys.timezone() time)

Value

Extracted data.tables for nested data returned from av_get_pf(), If grepstring is not specified, first nested table is returned. av_extract_fx() returns a shortened data.table with FX quotes.

See Also

av_get_pf(), av_grep_opts()

Examples

## Not run: 
av_get_pf("","MARKET_STATUS")  |> av_extract_df()
av_get_pf("","TOP_GAINERS_LOSERS") |> av_extract_df("top_losers")
av_get_pf("USD/BRL","CURRENCY_EXCHANGE_RATE") |> av_extract_fx()
av_get_pf(c("ORCL","IBM"),"ANALYTICS_FIXED_WINDOW") |> av_extract_analytics(separate_vars=TRUE)

## End(Not run)

Extract data from Alpha Vantage retuned data

Description

Extract data from Alpha Vantage retuned data

Usage

av_funhelp(av_fun_grep = "", verbose = TRUE)

Arguments

Details

Returns defaults and parameter lists for Alphavantage functions

Value

Help Text and default parameters.

See Also

av_get_pf()

Examples

av_funhelp("GLOBAL_QUOTE")

Get financial data from the Alpha Vantage API

Description

Interface to alphavantage API.

Usage

av_get_pf(
  symbol,
  av_fun,
  symbolvarnm = "symbol",
  dfonerror = TRUE,
  melted = "default",
  delay = 0,
  verbose = FALSE,
  ...
)

Arguments

Details

The av_fun argument replaces the API parameter “function” because function is a reserved name in R. All other arguments match the Alpha Vantage API parameters.

There is no need to specify the apikey, datatype, outputsize or entitlement parameters as arguments to av_get_pf(). Before using, you must set the API key using av_api_key("YOUR_API_KEY"). outputsize defaults to "full" unless overridden with "compact in ...."

Required parameters other than symbol must be passed as named arguments via ....

Optional parameters have defaults which can be obtained by calling av_funhelp() and overridden via ....

There is no need to specify the datatype parameter as an argument to av_get_pf(). The function will return a data.table.

ForEx "FROM/TO" symbol details. FOREX symbols in the av_get_pf() function are supplied in "FROM/TO" format, which are then parsed in the Alpha Vantage API into from_currency and to_currency API parameters. Usage example: av_get_pf("USD/BRL", "FX_DAILY")

Value

Returns a data.table with results dependent on the function called. Mixed data is returned as a melted data.table, possibly with nested data.frames. Time series are returned as data.tables.

See Also

avpf_api_key(), av_extract_df(), av_extract_fx(), av_grep_opts(),av_funhelp()

Examples

## Not run: 
avpf_api_key("YOUR_API_KEY","delayed") # or "realtime" if you have such access

# example code

# ---- 1.0 SINGLE NAME EQUITY SUMMARY INFORMATION AND SEARCH ----

av_get_pf("IBM","OVERVIEW") |> str()
av_get_pf("EWZ","ETF_PROFILE")
av_get_pf("EWZ","ETF_PROFILE") |> av_extract_df("holdings")
av_get_pf("","SYMBOL_SEARCH",keywords="COMMERCE")

# ---- 2.0 MARKET QUOTES  ----

av_get_pf("IBM","GLOBAL_QUOTE")
av_get_pf("USD/BRL","CURRENCY_EXCHANGE_RATE") |> av_extract_fx()
av_get_pf(c("ORCL","IBM","EWZ","ARGT"),"REALTIME_BULK_QUOTES",melt=FALSE)
# Note you need advanced permissioning for REALTIME_BULK_QUOTES

# ---- 3.0 SINGLE NAME HISTORICAL DATA  ----

av_get_pf("IBM","TIME_SERIES_DAILY")
av_get_pf("IBM","TIME_SERIES_INTRADAY")

# ---- 4.0 MARKET PRICING DATA  ----

av_get_pf("","MARKET_STATUS")  |> av_extract_df()
av_get_pf("","TOP_GAINERS_LOSERS") |> av_extract_df("top_losers")
av_get_pf("","TREASURY_YIELD",maturity='7year')

# ---- 4.0 SINGLE NAME NON-PRICING DATA  ----

av_get_pf("IBM","DIVIDENDS")
av_get_pf("IBM","EARNINGS")  |> av_extract_df("quarter",melt=TRUE)
av_get_pf("IBM","NEWS_SENTIMENT") |> av_extract_df("feed")

av_get_pf("IBM","EARNINGS_CALL_TRANSCRIPT",quarter="2024Q3")  |> av_extract_df("transcript")
 # Note that quarter is a required parameter, not specifying will throw an error

 # ---- 5.0 SINGLE NAME OPTION PRICING DATA  ----

av_get_pf("IBM","HISTORICAL_OPTIONS") |> av_grep_opts("F,M,put",mindays=2)

# ---- 6.0 TECHNICAL INDICATORS  ----

av_funhelp("SMA")  # Shows parameters and defaults chosen by this package.
av_get_pf("IBM","SMA",time_period=20)

# ---- 7.0 WINDOW ANALYTICS  ----

av_get_pf(c("ORCL","IBM","EWZ","ARGT"),"ANALYTICS_FIXED_WINDOW",verbose=TRUE) |>
            av_extract_analytics(separate_vars=TRUE)

## End(Not run)

Filter options from returned AV data

Description

Filter options from returned AV data

Usage

av_grep_opts(
  indta,
  grepstring = "F,M,C,otm",
  spot = NULL,
  mindays = 3,
  startdt = Sys.Date(),
  mindelta = 0.05,
  dropsymbol = FALSE
)

Arguments

Details

Alphavantage doesn't always return quarterly options

av_get_pf() returns a large list of options. This function helps to narrow down the list by maturity and moneyness.

Value

A reduced set of options obtained from av_get_pf() using Alphavantage HISTORICAL_OPTIONS function.

See Also

av_get_pf()

Examples

## Not run: 
av_get_pf("IBM","HISTORICAL_OPTIONS") |> av_grep_opts("F,M,put",mindays=2)

## End(Not run)

Load av_runShiny() internal data.

Description

Loads internal data (prices, earnings, etc.

Usage

av_load_shinydata(item = NULL, verbose = TRUE)

Arguments

Details

Load ShinyApp data from Cache

Value

Data item specified by item or a nothing (but a message) if left blank

See Also

av_runShiny()

Extract data from Alpha Vantage retuned data

Description

Extract data from Alpha Vantage retuned data

Usage

av_make_funcmap()

Details

Creates a data.table with API signatures and default values for Alphavantage API calls

Value

function map dat.table, also written to data directory

See Also

av_get_pf()

Examples

## Not run: 
av_make_funcmap()

## End(Not run)

Add additional columns to returned option sets

Description

Add additional columns to returned option sets

Usage

av_opt_helper_cols(indta, scaling = NULL, spot_override = NULL)

Arguments

Details

Adds columns including

Value

An option data.table with extra columns helpful for further analysis

See Also

av_grep_opts()

Examples

## Not run: 
av_get_pf("IBM","HISTORICAL_OPTIONS") |> av_grep_opts("F,M,put",mindays=2) |> av_opt_helper_cols()

## End(Not run)

Extract data from Alpha Vantage retuned data

Description

Extract data from Alpha Vantage retuned data

Usage

av_reset_defaults(fileopts = TRUE, keep_apikeys = FALSE, resetgrep = "*")

Arguments

Details

Resets av_runShiny() defaults to original (newly installed) state

Value

No return

See Also

av_runShiny()

Examples

## Not run: 
av_reset_defaults()

## End(Not run)

RShiny App

Description

av_runShiny() runs an interactive RShiny app with a professional command line interface to download, manage, and visualize data from the Alpha Vantage data service. The app treats equities, ETFs, indices, and FX equally, so users do not need to know specific API calls to integrate data. Downloaded data is cached to reduce API calls, all data can be saved for external use, and both external data and external commands (that call user functions) can be added to the app. Sets of securities can be easily added and managed.

Usage

av_runShiny()

Details

Invocation starts Shiny application. See vignettes for full details. On first use, In the AVOPTS tab, fill in the following fields, and hit the "Set Opts" button.

• AV API Key: API key obtained from Alpha Vantage

• Entitlement Entitlement status (either delayed or realtime) Other options that can be set are given below.

To get data and run analyses: Enter in the top yellowed line a semicolon delimited set of securities (Equity, ETF, FX, Crypto, indices) followed by a command to run analytics on those securities. Commands without securities are always prefixed by '"AV.". The results are shown as tables, plots, or dygraphs below the command line, and possibly in an additional tab to the right of the main tab. The secondary tab will change names as approprriate, and the focus may be changed off the MAIN tab.

Commands are not case sensitive, and may refer to a counterasset in the second yellowed line. A few examples include:

If an analysis requires price, dividend or earnings data that is not in the app's internal store, then it will download it as necessary from Alpha Vantage. Other data (e.g. News, options) are downloaded freshly each time. One of the key contributions of this app is to abstract out the asset-specific functions calls that are necessary to do cross-asset analyses.

Other niceties:

• Groups of assets can be named, saved, and recalled easily. The saved name can then be used in lieu of the original list. See Basic Usage vignette

• Internal data can be stored and used (as data.table()s) in a directory of the users' choosing. See Options vignette to set the directory, and the Data vignette for details on how the data is structured.

• Events and other plotting options can be specified in the app. See functions vignette and e.g. FinanceGraphs

• Data within each produced graph or table can be copied to the clipboard (option in AVOPTS page), See Setup vignette to see where to turn this on.

• Raw downloaded data can be saved into a "dump directory" (option in AVOPTS page)

• A current inventory list is always kept in a separate tab, avoiding having to run AV.INV repeatedly.

• User price data, earnings data, and asset groups can be added using helper functions av_add_px(), av_add_earn(), av_add_assetgroups(). See data vignette. Adding data from the console immediately adds the data to the app.

• User analytics can be added using av_add_analytic(). See examples in the Extensions vignette

Value

Nothing

A ShinyAppHandle object.

Examples

## Not run: 
av_runShiny()

## End(Not run)

av_state_interface

Description

retrieves internal data state of av_runShiny() dump_state(typegrep="*") dump_inv(invgrep="*") dump_assetgroups() dump_captured(todo="byfunction") av_shiny_px()

Usage

dump_state(typegrep = "*")

dump_inv(invgrep = "*")

dump_assetgroups()

dump_av_funcs()

dump_captured(todo = "byfunction")

Arguments

Details

Return av_runShiny data and states

Value

data.table with desired data.

See Also

av_runShiny()

Examples

## Not run: 
`dump_state()`
`dump_inv()`
`dump_av_funcs()`
`dump_assetgroups()`
`dump_captured(todo="byfunction")`

## End(Not run)

Set the Alpha Vantage API Key

Description

avpf_api_key() sets Alphavantage API key and entitlement code

Usage

avpf_api_key(api_key, entitlement = NULL)

Arguments

Details

The Alpha Vantage API key must be set prior to using av_get_pf(). You can obtain an API key at the Alpha Vantage Website.

Value

Invisibly returns two item list with API key and entitlement string once set). Use print method to view.

See Also

av_get_pf()

Examples

## Not run: 
avpf_api_key("YOUR_API_KEY",entitlement="delayed")
av_get_pf("IBM", "TIME_SERIES_INTRADAY")

## End(Not run)

avsh_clipboard

Description

Copies a data.frame to the clipboard, with a status message if relevant

Usage

avsh_clipboard(x, title = "")

Arguments

Details

Copy data to clipboard

Value

Nothing

avsh_quick_message

Description

Displays a message underneath an input box

Usage

avsh_quick_message(this_message, eval = TRUE, color = "#1f78b4")

Arguments

Details

Display a user message in the av_runShiny app

Value

logical value of eval

avsh_set_tabtitle

Description

Sets the title for the Details tab

Usage

avsh_set_tabtitle(newtext = "DETAIL", tabnm = "detail", makefocus = TRUE)

Arguments

Details

Set an av_runShiny Tab Title

Value

Nothing

App formatting functions

Description

Adds default elements to gt() table

Usage

gt.basetheme(
  x,
  gtopts = "all",
  sizepct = 100,
  style = 4,
  digits = 2,
  interactive_mult = 1.14,
  seps = FALSE,
  na_format = "-",
  size = "",
  interactive = ""
)

Arguments

av_runShiny utilities

Description

Prints message if condition met

Usage

message_if(reallydothis, ...)

Arguments