#250 tq_fund_holdings()

NAMESPACE

@@ -162,6 +162,8 @@ export(tidyquant_conflicts)
 export(tiingo_api_key)
 export(tq_exchange)
 export(tq_exchange_options)
+export(tq_fund_holdings)
+export(tq_fund_source_options)
 export(tq_get)
 export(tq_get_options)
 export(tq_index)

NEWS.md

@@ -1,13 +1,20 @@
 # tidyquant 1.0.9
 
-- Fixes to CRAN's API policy:
+## New Function: 
+
+- `tq_fund_holdings()`: Retrieves the fund holdings and compositions for a fund and source combination. Example: `tq_fund_holdings("SPY", source = "SSGA")` #250
+
+## Fixes and Improvements:
+
+- Fixes to CRAN's API policy #249:
 
 > "Packages which use Internet resources should fail gracefully with an
 informative message if the resource is not available or has changed (and
 not give a check warning nor error)."
 
 
 
+
 # tidyquant 1.0.8
 
 ## TQ INDEX AND EXCHANGE:

R/tq_stock_list.R

@@ -22,12 +22,21 @@
 #' `tq_exchange_options()` returns a list of stock exchanges you can
 #' choose from. The options are AMEX, NASDAQ and NYSE.
 #'
+#' `tq_fund_holdings()` returns the the stock symbol, company name, weight, and sector of every stock
+#' in an fund. The `source` parameter specifies which investment management company to use.
+#' Example: `source = "SSGA"` connects to State Street Global Advisors (SSGA).
+#' If `x = "SPY"`, then SPDR SPY ETF holdings will be returned.
+#'
+#' `tq_fund_source_options()`: returns the options that can be used for the `source` API for `tq_fund_holdings()`.
+#'
 #' @seealso
 #' [tq_get()] to get stock prices, financials, key stats, etc using the stock symbols.
 #'
 #'
 #' @examples
 #'
+#' # Stock Indexes:
+#'
 #' # Get the list of stock index options
 #' tq_index_options()
 #'
@@ -36,6 +45,8 @@
 #' tq_index("DOW")
 #' }
 #'
+#' # Stock Exchanges:
+#'
 #' # Get the list of stock exchange options
 #' tq_exchange_options()
 #'
@@ -44,6 +55,16 @@
 #' tq_exchange("NYSE")
 #' }
 #'
+#' # Mutual Funds and ETFs:
+#'
+#' # Get the list of stock exchange options
+#' tq_fund_source_options()
+#'
+#' # Get all stocks in a fund
+#' \dontrun{
+#' tq_fund_holdings("SPY", source = "SSGA")
+#' }
+#'
 #' @name tq_index
 #' @export
 
@@ -95,7 +116,7 @@ tq_index <- function(x, use_fallback = FALSE) {
 
     # Download the index data
     dload <- tryCatch({
-        index_download(x_spdr, index_name = x)
+        ssga_download(x_spdr, index_name = x)
     }, error = function(e) {
         warning(paste("Error downloading index data:", e$message), call. = FALSE)
         return(NULL)
@@ -118,6 +139,18 @@ tq_index <- function(x, use_fallback = FALSE) {
     df
 }
 
+#' @rdname tq_index
+#' @export
+tq_index_options <- function() {
+    c(
+        "DOW",
+        "DOWGLOBAL",
+        "SP400",
+        "SP500",
+        "SP600"
+    )
+}
+
 
 # tq_exchange ----
 
@@ -215,21 +248,69 @@ tq_exchange <- function(x) {
 
 #' @rdname tq_index
 #' @export
-tq_index_options <- function() {
-    c(
-      "DOW",
-      "DOWGLOBAL",
-      "SP400",
-      "SP500",
-      "SP600"
-      )
+tq_exchange_options <- function() {
+    c("AMEX", "NASDAQ", "NYSE")
 }
 
+# tq_fund_holdings ----
 
 #' @rdname tq_index
+#' @param source The API source to use.
 #' @export
-tq_exchange_options <- function() {
-    c("AMEX", "NASDAQ", "NYSE")
+tq_fund_holdings <- function(x, source = "SSGA") {
+
+    # Verify index
+    verified <- tryCatch({
+        verify_fund_source(source)
+    }, error = function(e) {
+        warning(paste("Error verifying index:", e$message), call. = FALSE)
+        return(NULL)
+    })
+
+    # If verification failed or not a verified index, return a warning and empty tibble
+    if(is.null(verified) || !verified$is_verified) {
+        warning(verified$err)
+        return(tibble::tibble())
+    }
+
+    # Download the index data
+    dload <- tryCatch({
+        source <- stringr::str_to_upper(source)
+
+        if (source == "SSGA") {
+            ssga_download(x, index_name = x)
+        } else {
+
+        }
+
+
+    }, error = function(e) {
+        warning(paste("Error downloading index data:", e$message), call. = FALSE)
+        return(NULL)
+    })
+
+    # If download failed, return a warning and empty tibble
+    if(is.null(dload) || !is.null(dload$err)) {
+        warning(dload$err)
+        return(tibble::tibble())
+    }
+
+    # Clean holdings
+    df <- tryCatch({
+        clean_holdings(dload$df)
+    }, error = function(e) {
+        warning(paste("Error cleaning index holdings:", e$message), call. = FALSE)
+        return(tibble::tibble())
+    })
+
+    df
+
+}
+
+#' @rdname tq_index
+#' @export
+tq_fund_source_options <- function() {
+    c("SSGA")
 }
 
 # Utility ----------------------------------------------------------------------------------------------------
@@ -261,6 +342,23 @@ verify_index <- function(x) {
     verified
 }
 
+verify_fund_source <- function(x) {
+
+    # Setup with initial values
+    verified <- list(is_verified = FALSE, err = "")
+
+    if(!(x %in% tq_fund_source_options())) {
+
+        verified$err <- paste0(x, " must be a character string in the form of a valid Fund Source. ",
+                               "The following are valid options:\n",
+                               stringr::str_c(tq_fund_source_options(), collapse = ", "))
+    } else {
+        verified$is_verified <- TRUE
+    }
+
+    verified
+}
+
 # Map the index to the SPDR ETF name
 spdr_mapper <- function(x) {
 
@@ -281,7 +379,7 @@ spdr_mapper <- function(x) {
 }
 
 # Download the index data from SPDR
-index_download <- function(x, index_name) {
+ssga_download <- function(x, index_name) {
 
     # Contruct download link
     #     OLD (< 2019-12-15): https://us.spdrs.com/site-content/xls/SPY_All_Holdings.xls

_pkgdown.yml

@@ -49,6 +49,7 @@ reference:
   - starts_with("tq_get")
   - starts_with("tq_index")
   - starts_with("tq_exchange")
+  - starts_with("tq_fund")
 - subtitle: API Keys
   contents:
   - starts_with("quandl")