---
title: "Using the `tidyfinance` package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using the `tidyfinance` package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`tidyfinance` is an R package [on CRAN](https://CRAN.R-project.org/package=tidyfinance) that contains a set of helper functions for empirical research in financial economics, addressing a variety of topics covered in [Tidy Finance with R](https://www.tidy-finance.org/r/) (TFWR). We designed the package to provide easy shortcuts for the applications that we discuss in the book. If you want to inspect the details of the package or propose new features, feel free to visit the package repository on [Github](https://github.com/tidy-finance/r-tidyfinance).

In this vignette, we demonstrate the features of the initial release. We decided to focus on functions that allow you to download the data that we use in TFWR. 

## Install the package

You can install the released version of `tidyfinance` from CRAN via:

```{r}
#| eval: false
install.packages("tidyfinance")
```

You can install the development version of tidyfinance from GitHub using the `pak` package:

```{r}
#| eval: false
pak::pak("tidy-finance/r-tidyfinance")
```

## Download data 

Let's start by loading the package

```{r}
library(tidyfinance)
```

The main function is `download_data(type, start_date, end_date)` with supported type:
```{r}
list_supported_types()
```

So, for instance, if you want to download monthly Fama-French Three-Factor data, you can call:
```{r}
#| eval: false
download_data("factors_ff_3_monthly", "2020-01-01", "2020-12-31")
```

Under the hood, the function uses the `frenchdata` package (see its documentation [here](https://CRAN.R-project.org/package=frenchdata)) and applies some cleaning steps, as in TFWR. If you haven't installed `frenchdata` yet, you'll get prompted to install it first before you can download this specific data type. 

You can also access q-Factor data in this way, by calling:

```{r}
#| eval: false
download_data("factors_q5_daily", "2020-01-01", "2020-12-31")
```

To ensure that we can extend the functionality of the download functions for specific types, we also provide domain-specific download functions. The `download_data("factors_ff_3_monthly")` actually calls `download_data_factors("factors_ff_3_monthly")`, which in turn calls `download_data_factors_ff("factors_ff_3_monthly")`. Why did we decide to have these nested function approach?

Suppose that the q-Factor data changes its URL path and our original function does not work anymore. In this case, you can replace the default `url` value in `download_data_factors_q(type, start_date, end_date, url)` to apply the usual cleaning steps. 

This feature becomes more apparent for other data sources such as `wrds_crsp_monthly`. Note that you need to have valid WRDS credentials and need to set them correctly (check `?set_wrds_connection()` and [WRDS, CRSP, and Compustat](https://www.tidy-finance.org/r/wrds-crsp-and-compustat) in TFWR). If you want to download the standard monthly CRSP data, you can call:

```{r}
#| output: false
#| eval: false
download_data("wrds_crsp_monthly", "2020-01-01", "2020-12-31")
```

If you want to add further columns, you can add them via `additional_columns` to `download_data_wrds_crsp()`, for instance:

```{r}
#| output: false
#| eval: false
download_data_wrds_crsp("wrds_crsp_monthly", "2020-01-01", "2020-12-31", additional_columns = "mthvol")
```

Note that the function downloads CRSP v2 as default, as we do in our book since February 2024. If you want to download the old version of CRSP before the update, you can use the `version = v1` parameter in `download_data_wrds_crsp()` . 

As another example, you can do the same for Compustat:

```{r}
#| output: false
#| eval: false
download_data_wrds_compustat("wrds_compustat_annual", "2000-01-01", "2020-12-31", additional_columns = c("acoxar", "amc", "aldo"))
```

Check out the list of supported types and the corresponding download functions for more information on the respective customization options. We decided to provide limited functionality for the initial release on purpose and rather respond to community request than overengineer the package from the start.  

## Browse content from TFWR

We include functions to check out content from TFWR in your browser. If you want to list all available R chapters, simply call the following function:

```{r}
list_tidy_finance_chapters()
```

The function returns a character vector containing the names of the chapters available in TFWR. If you want to look at a specific chapter, you can call:

```{r}
#| eval: false
open_tidy_finance_website("beta-estimation")
```

This opens either the specific chapter you requested or the main index page in your default web browser. 

## Regression helpers

We discuss winsorization in TFWR, so we figured providing this function could be useful:

```{r}
#| message: false
#| warning: false
library(dplyr)

set.seed(123)
data <- tibble(x = rnorm(100)) |>
  arrange(x)

data |>
  mutate(x_winsorized = winsorize(x, 0.01))
```

If you rather want to replace the bottom and top quantiles of your distribution with missing values, then you can use `trim()`

```{r}
data |>
  mutate(x_trimmed = trim(x, 0.01))
```

We also discuss the importance of providing summary statistics of your data, so there is also a function for that:

```{r}
create_summary_statistics(data, x, detail = TRUE)
```

## Experimental functions

We have two more experimental functions in the sense that it is unclear in which direction they might evolve. First you can assign portfolios based on a sorting variable using `assign_portfolio()`:

```{r}
data <- tibble(
  id = 1:100,
  exchange = sample(c("NYSE", "NASDAQ"), 100, replace = TRUE),
  market_cap = runif(100, 1e6, 1e9)
)

data |>
  mutate(
    portfolio = assign_portfolio(
      pick(everything()), "market_cap", list(n_portfolios = 5, breakpoint_exchanges = "NYSE"))
  )
```

Second, you can estimate the coefficients of a linear model specified by one or more independent variable using `estimate_model()`:

```{r}
data <- tibble(
  ret_excess = rnorm(100),
  mkt_excess = rnorm(100),
  smb = rnorm(100),
  hml = rnorm(100)
)

estimate_model(data, "ret_excess ~ mkt_excess + smb + hml")
```

## Concluding remarks

We are curious to learn in which direction we should extend the package, so please consider opening an issue in the [package repository](https://github.com/tidy-finance/r-tidyfinance/issues). For instance, we could support more data sources, add more parameters to the `download_*` family of functions, or we could put more emphasis on the generality of portfolio assignment or other modeling functions.