---
title: "FRED Categories"
author: "Sam Boysel"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{FRED Categories}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r setup, include = FALSE}
library(fredr)

knitr::opts_chunk$set(
  fig.width = 7,
  fig.height = 5,
  eval = fredr_has_key(),
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction

```{r}
library(fredr)
```

This vignette is intended to introduce the user to fredr functions for the [Categories endpoint](https://fred.stlouisfed.org/docs/api/fred/#Categories) of the FRED API.

FRED series are assigned **categories**. Each FRED category is assigned an integer identifier. For example:

-   "Population, Employment, & Labor Markets" (`category_id = 10`)
-   "National Accounts" (`category_id = 32992`)
-   "Production & Business Activity" (`category_id = 1`)
-   "Housing" (`category_id = 97`)

Categories are organized in a hierarchical structure where parent categories contain children categories. All categories are children of the root category (`category_id = 0`). The following examples illustrate usage of the Categories endpoint functions in fredr.

## Get a FRED category

`fredr_category()` returns minimal information for a single category specified by `category_id`. The data returned is a `tibble` in which each row represents a category.

```{r fredr_category1}
fredr_category(category_id = 0L) 
```

```{r fredr_category2}
fredr_category(category_id = 97L)
```

## Get the children of a FRED category

`fredr_category_children()` returns minimal information (child ID, name, and parent ID) for all child categories of the parent category specified by `category_id`. The data returned is a tibble in which each row represents child category of the parent specified.

```{r fredr_category_children1}
fredr_category_children(category_id = 0L)
```

```{r fredr_category_children2}
fredr_category_children(category_id = 1L)
```

## Get a related FRED category

`fredr_category_related()` returns minimal information (ID, name, and parent ID) for all related categories to the category specified by `category_id`. The data returned is a tibble in which each row represents category related to the one specified. Note that not all categories have related categories.

```{r fredr_category_related1}
# Nothing related to the root
fredr_category_related(category_id = 0L)
```

```{r fredr_category_related2}
# What is related to the Employment Cost Index category?
fredr_category_related(category_id = 4L)
```

## Get series in a category

`fredr_category_series()` returns detailed information for the FRED series belonging to the category specified by `category_id`. The data returned is a tibble in which each row represents a series belonging to the category specified. For example, to get the top 100 quarterly series in the "Housing" category, ordering the results so that the most recently updated series appear first:

```{r fredr_category_series1}
fredr_category_series(
  category_id = 97L, # Housing
  limit = 100L,
  order_by = "last_updated",
  filter_variable = "frequency",
  filter_value = "Quarterly"
)
```

To return all series in the "National Accounts" category tagged with `"usa"` and *not* `"gnp"`, ordering the results such that higher frequency series appear first:

```{r fredr_category_series2}
fredr_category_series(
  category_id = 32992L, # National Accounts
  order_by = "frequency",
  sort_order = "desc",
  tag_names = "usa",
  exclude_tag_names = "gnp"
)
```

## Get tags within a FRED category

`fredr_category_tags()` returns information for the FRED tags assigned to series in the category specified by `category_id`. The data returned is a tibble in which each row represents a tag assigned to a series in the category specified. For example, to get all "source" tags belonging to series in the "Retail Trade" category:

```{r fredr_category_tags1}
fredr_category_tags(
  category_id = 6L,
  tag_group_id = "src"
)
```

To search for tags with the words `"usa"` in the "Production & Business Activity" category, ordering the results by popularity:

```{r fredr_category_tags2}
fredr_category_tags(
  category_id = 1L,
  search_text = "usa",
  order_by = "popularity",
  sort_order = "desc"
)
```

## Get related tags within a FRED category

`fredr_category_related_tags()` returns a set of FRED tags assigned to series in the category specified by `category_id` that are *related* to the tags specified in the `tag_names` parameter. The data returned is a tibble in which each row represents a tag *related to* a tag assigned to a series in the specified category. For example, to get all tags *except* `"rate"` in the "Retail Trade" category related to the tags `"business"` and `"monthly"`, ordering the results alphabetically:

```{r fredr_category_related_tags1}
fredr_category_related_tags(
  category_id = 1L,
  tag_names = "business;monthly",
  exclude_tag_names = "rate",
  order_by = "name"
)
```