In UBC-MDS/rintrinio: R package that draws needed data from intrinio API objects

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(devtools)

api_key <- 'OjhlMjhjNTBmY2IyMWJiMWE0MTExYjQwNWZmZTVkZWM1'

rintrinio

R [@R] package converts Intrinio [@intrinio] objects and lists to dataframes.

The vignette can be found here.

The Project

This project has been created as part of UBC's Master of Data Science Program. Information about the contributors can be found here. The Code of Conduct can be found here. The collaboration expectations regarding use of Github Flow can be found here.

If you were to search the web for "historical stock data", or "financial statement data", the results you would come across would be a variety of web applications (such as Google Finance), and maybe some PDFs of financial statements. This is fair, as there is a massive volume of stock data, and financial statements require lots of discretion (including standards followed - US companies may choose between reporting under IFRS and US GAAP). Intrinio offers solutions to this problem with an API platform that can easily be used to extract data and perform further analysis on it.

Intrinio is an excellent source to get data into the R environment to analyse data, but a problem persists that the data can't be directly analysed from Intrinio objects. That is where rintrinio comes in. This package will offer a variety of functions that allow users to seamlessly transform Intrinio objects into dataframes. This will enable users of the data to make the most of Intrinio's reliable and easy-to-use API platform, as well as the analysis capabilities that are available in R's environment.

rintrinio in the R Ecosystem

R is an object-oriented programming language, which has allowed contributors of packages to make complex data types appear simple, and overall make packages easy for users to use. R's native dataframe object is extremely popular and widely accepted in the R ecosystem. Intrinio's API platform for R actually has a function that is supposed to return the results as a dataframe object, but it is actually a list that is returned. This package will transform Intrinio objects into dataframes that will make this data ready for the end user to use.

Installation

You can install the current version of rintrinio from github with:

library(devtools)
devtools::install_github("UBC-MDS/rintrinio")

Coverage

To get the line coverage, run the following from the R Console:

if(!require(covr)) { install.packages("covr") }
library("covr")
covr::report()

Dependencies

Getting an API Key

Before using any functions included in this package, you must sign up for an appropriate Intrinio account. Once you have signed up for the appropriate account, you can find your API key (which is a required argument in all functions) by doing the following:

1. In the top right corner, select My Account
2. In the left hand menu, select API KEYS
3. Copy your relevant API Key. Note that this is unique to you and should not be shared.

If you are using a free version of Intrinio for educational purposes, please note that you will only have access to the Developer Sandbox so use that API key in functions.

Note that the API key must be of type character when it is used in our functions. Hence, don't forget to use quotation marks when you use your API key.

Installing Intrinio R SDK

Please note that the Intrinio R SDK is not available via CRAN. To install, follow these steps, as outlined in the Intrinio R Documentation. Note that Intrinio R SDK should be installed prior to installing rintrinio.

In an R console, install devtools if it is not already installed:

if(!require(devtools)) { install.packages("devtools") }

Install Intrinio SDK from Github:

library(devtools)
devtools::install_github("intrinio/r-sdk")

Program and Package Dependencies

R version 3.6.1 and R packages:

• knitr==1.26 [@knitr]
• tidyverse==1.2.1 [@tidyverse]
• IntrinioSDK==0.1.0 [@intrinio]
• testthat==2.3.1 [@testthat]

Functions

1. gather_financial_statement_time_series(): This function takes in a single stock ticker symbol, the statement, the year, and a vector of various periods to compare. It returns a data frame of the information in the selected statement, for a time-series analysis of the company specified.
2. gather_financial_statement_company_compare(): This function takes in a vector containing the tickers of the companies we want to compare, the statement we want to focus on, and the year and the period of the year we want to study. It returns a dataframe of the information in the selected statement, for the selected companies at the wanted time.
3. gather_stock_time_series(): This function takes in a single stock ticker symbol and returns historical stock price data from a timeframe, returned as a dataframe.
4. gather_stock_returns(): This function takes in multiple stock ticker symbols, buy-in date, sell-out date and returns a dataframe containing the historical prices at buy-in and sell-out date as well as the corresponding returns (profit/loss).

Usage

library(rintrinio)

# Gather Financial Statement Time Series Function
gather_financial_statement_time_series(api_key = api_key, 
                                       ticker = 'AAPL', 
                                       statement = 'balance_sheet_statement', 
                                       year = c("2018", "2019"),
                                       period = c('Q1'))

# Gather Financial Statement Cross-Company Comparison Function
gather_financial_statement_company_compare(api_key = api_key, 
                                           ticker = c("AAPL", "CSCO"), 
                                           statement = "income_statement", 
                                           year = "2018", 
                                           period = "Q1")

# Gather Stock Price Time Series Function
gather_stock_time_series(api_key = api_key,
                         ticker = "CSCO",
                         start_date = "2020-02-01",
                         end_date = "2020-02-05")

# Gather Stock Returns Function
gather_stock_returns(api_key = api_key,
                     ticker = c("AAPL", "CSCO"),
                     buy_date = "2019-01-01",
                     sell_date = "2020-01-01")

If you are using a Sandbox API key, the following tickers will work in all of the functions: 'AAPL', 'AXP', 'BA', 'CAT', 'CSCO', 'CVX', 'DIS', 'DWDP', 'GE', 'GS', 'HD', 'IBM', 'INTC', 'JNJ', 'JPM', 'KO', 'MCD', 'MMM', 'MRK', 'MSFT', 'NKE', 'PFE', 'PG', 'TRV', 'UNH', 'UTX', 'V', 'VZ', 'WMT', 'XOM'

Available statements include: 'income_statement', 'balance_sheet_statement', 'cash_flow_statement'

References

UBC-MDS/rintrinio documentation built on March 31, 2020, 12:54 a.m.