---
title: "IEX Stocks and Market Data via IEX API"
author: "Myriam Ibrahim"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{IEX Stocks and Market Data via IEX API}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The main goal of `Riex` is to efficiently retrieve financial and market data using `IEX Cloud API`. In addition, provide robust tool to:

- Enable data analysis and visualization
- Monitor account usage and alerts

Please make sure to review and acknowledge [IEX Terms of Use](https://iexcloud.io/terms/) before using `Riex`.

Effective June 1st, 2019, subscription will be required to access third party data.

For subscriptions details, visit [IEX - Flexible, scalable pricing](https://iexcloud.io/pricing/).

- Multiple tiers are available to users depending on their requirements with capability to upgrade
- Usage is measured based on message counts which  depends on API Call and associated weight
- Example [Company - API Call](https://iexcloud.io/docs/api/#company) has a weight of 1 for each Symbol

Additional details about usage calculations available in [Data Weight - section](https://iexcloud.io/docs/api/#how-credits-work) as well as best practice about storing and sharing [Private & Public Secret Key](https://iexcloud.io/docs/api/#authentication)

## Installation

You can `install` the released version of Riex from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("Riex")
```

## Examples

Following are basic examples that will demonstrate how to use `Riex` to retrieve Stock and Market information via `IEX Cloud API`.

List of parameters and their valid values:

-  iex_sk : `IEX Cloud API` **Secret Token**.

   *Secret Token* is available to use via Account Console and assigned the variable **sk** in the documentation. e.g. sk <- "sk_xxxxxx".
   Please note that term "*Secret Token*" and "*Secret Key*" are used interchangeably in `Riex` documentation  

   Keep your **Secret Token** safe. Your **Secret Token** can make any API call on behalf of your account, 
   including changes that may impact billing such as enabling pay-as-you-go charges. 
   
-  x : A valid IEX Stock Symbol
-  p : "annual" or "quarter" 
-  r : Takes only of of the values accepted in API request. {"5y", "2y", "1y", "ytd", "6m", "3m", "1m", "1d"}


## Load `Riex`

```{r load, echo=TRUE}
library(Riex)
```
- Assign Secret key to Variable **sk**
```r
sk <- "[SECRET KEY]"
```
- Assign valid stock symbol to **x**
```{r symbol, echo=TRUE}
x <- "TSLA"
```
- Assign valid period to variable **r**
```{r period, echo=TRUE}
r <- "6m"
```
## Chart
```r
TSLA <- iex.chart(x, r, sk)
```

Load `quantmod` package

```r
library(quantmod)
```

Generate Barchart

```r
barChart(TSLA)
```
```{r, echo=FALSE, message=FALSE, fig.cap='TSLA 6 Months Chart', fig.align='center'}
knitr::include_graphics("./TSLA_6M_Chart.png")
```

<!--![TSLA 6 Months Chart](/Users/Myriam/Documents/R/Riex/vignettes/TSLA_6M_Chart.png)-->

To check available themes to customize  visualization

```r
names(quantmod:::.chart.theme)
```
To apply a different Theme

```r
barChart(TSLA, theme="white")
```

If you receive an error run:

```r
par("mar")
```
In case response is similar to the following: [1] 5.1 4.1 4.1 2.1, then run:

```r
par(mar=c(1,1,1,1))
barChart(TSLA)
```

```r
chartSeries(TSLA)
```

When possible, results from functions matches OHLC standards for `quantomd` package to leverage its capabilities. Future enhancements to `Riex` will be geared toward enabling comprehensive financial analysis & modeling.

Refer to `quantomd` documentation for additional details about customizing visualization.

## Most Active
```r 
Most_Active <- iex.most.active(sk)
Most_Active['companyName']
```
## Book
```r
iex.book("GM", sk)
```
## Earnings
```r
iex.earnings("GM", sk)
```
## Financials 
  The following default functions retrieve income statement, balance sheet, and cash flow data from the most recent reported quarter.
  Upon further testing of `IEX Cloud API`, additional parameter *"p"* will be added  to allow user to specify annual or quarterly financials.
  
  - iex.balance.sheet (x, sk)
  - iex.cash.flow (x, sk)
  - iex.income (x, sk)
  
Results are rendered in data frame format to allow further manipulation in case of multiple stocks

```r
GM_BS <- iex.balance.sheet("GM", sk)
str(GM_BS)
``` 

Similarly, you can generate the previous quarter Income Statement and Cash Flow statement:

```r 
GM_IS <- iex.income("GM", sk)
GM_CF <- iex.cash.flow("GM", sk)
``` 
   
## Key Stats
Function returns a data frame that includes 20 observations - e.g. PE ratio, number of employees and 52 Weeks high and low, ..etc.

```r
iex.stats("TSLA", sk)
```
## Crypto
```r
Bitcoin <- crypto("BTCUSDT", sk)
Bitcoin
```

list of available crypto currency symbols in `IEX` as of April 26th, 2019 is included as dataset with `Riex` package and can be viewed using **crypto_symbols**.

```r
crypto_symbols
```

for most current list, Visit [IEX-Reference Data](https://iexcloud.io/docs/api/#reference-data) 

## Company Information

```r
TSLA_Co <- iex.company(x, sk)
```
## Company Logo

```r
TSLA_Logo <- logo (x, sk)
```
To store image in current directory, use:

```r
download.file(TSLA_Logo,"TSLA.png",mode="wb")
```

To check current directory path:

```r
getwd()
```

```{r, echo=FALSE, message=FALSE, fig.cap='TSLA Logo', fig.align='center'}
knitr::include_graphics("./TSLA.png")
```
<!--![TSLA Logo](/Users/Myriam/Documents/R/Riex/vignettes/TSLA.png)-->

## Account

Visit [IEX Cloud API - Account Section](https://iexcloud.io/docs/api/#account) for more details.
The following functions provide Account and usage details based on **Secret Token** provided. Please make sure to monitor usage regularly as it impacts billing depending on your Account setup.

## Account Metadata
Output includes **Total Message Limit** and **Total Message Used** in addition to useful info. - e.g. Tier Name

```r
iex.account(sk)
```
## Usage
Output includes **Monthly Usage**, **Monthly Pay As You Go** and **Token Usage**.

```r
iex.usage(sk)
```
## Key Usage

Key Usage includes the detailed usage by API Call type. 

```r
iex.key.usage (sk)
```
For example:

- STOCK_QUOTE
- HISTORICAL_PRICES
- COMPANY
- REF_DATA
- CRYPTO_QUOTE
- COMPANY_LOGO
- EARNINGS
- KEY_STATS
- ACCOUNT_USAGE
- CASH_FLOW
- BALANCE_SHEET
- INCOME

Type with "0" usage are included as well. For example, ACCOUNT_USAGE.

## Daily Usage
Output includes Total usage per day. Date format is xyyyymmdd - e.g. X20190423

```r
iex.daily.usage(sk)
```
## Monthly Usage
Output includes Total usage per month. 

```r
iex.monthly.usage(sk)
```

## Quote of the Day and Everyday !

> "He who gives up [code] safety for [code] speed deserves neither."
- [Hadley Wickham](https://twitter.com/hadleywickham/status/504368538874703872)


```{r, echo=FALSE, message=FALSE, fig.cap='Hadley Wickham Quote', fig.align='center'}
knitr::include_graphics("./HadleyWickham_Quote.png")
```

<!--![Hadley Wickham Quote](/Users/Myriam/Documents/R/Riex/vignettes/HadleyWickham_Quote.png)-->
