---
title: "FRED Tags"
author: "Sam Boysel"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{FRED Tags}
  %\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(),
  cache = TRUE,
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction

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

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

FRED series are assigned **tags** as an attribute for classification. Each FRED tag is identified by a string ID. For example:

-   "annual", "monthly"
-   "census", "bls"
-   "usa", "county"
-   "manufacturing", "exports", "households"
-   "sa" (i.e. "seasonally adjusted")

The following examples illustrate usage of the Tags endpoint functions in fredr.

## Get series tags

The function `fredr_tags()` returns a list of tags matching the request. The data returned is a tibble in which each row represents a FRED tag. For example, running `fredr_tags()` without any parameters returns the top 1000 FRED tags ordered by number of series who are assigned the tag (but here we limit to just 10):

```{r fredr_tags1, message=FALSE, warning=FALSE}
fredr_tags(limit = 10)
```

To return specific tags by tag name, specify multiple tags in a single string by delimiting with a semicolon:

```{r fredr_tags2, message=FALSE, warning=FALSE}
fredr_tags(tag_names = "gdp;oecd", limit = 10)
```

Return tags for a given group ID:

```{r fredr_tags3, message=FALSE, warning=FALSE}
fredr_tags(
  tag_group_id = "geo",
  limit = 50L
)
```

Search for tags by text:

```{r fredr_tags4, message=FALSE, warning=FALSE}
fredr_tags(search_text = "unemployment")
```

Note that the example above searches for *tags* matching `"unemployment"`. To search for the set of *series* with tags matching `"unemployment"`, use `fredr_series_search_tags()`:

```{r fredr_tags5, message=FALSE, warning=FALSE}
fredr_series_search_tags(
  series_search_text = "unemployment",
  limit = 100L
)
```

## Get related series tags

The function `fredr_related_tags()` returns a list of tags *related to* the set of tags matching the request. The data returned is a tibble in which each row represents a tag related to the tags specified in `tag_names`. For example, to get the set of tags related to the tags `"monetary aggregates"` and `"weekly"`:

```{r fredr_related_tags1}
fredr_related_tags(tag_names = "monetary aggregates;weekly")
```

To filter these results to tags belonging to the "General" tag group:

```{r fredr_related_tags2}
fredr_related_tags(
  tag_names = "monetary aggregates;weekly",
  tag_group_id = "gen"
)
```

To filter these results even further, keep only the tags matching the string `"money stock"`:

```{r fredr_related_tags3}
fredr_related_tags(
  tag_names = "monetary aggregates;weekly",
  tag_group_id = "gen",
  search_text = "money stock"
)
```

## Get series by tag names

The function `fredr_tags_series()` returns a list of series assigned tags matching the request. As with the functions for the [Series endpoint](http://sboysel.github.io/fredr/reference/index.html#Series), the data returned is a tibble in which each row represents a series. For example, to get all series tagged with `"gdp"`:

```{r fredr_series_tags1}
fredr_tags_series(tag_names = "gdp")
```

To get the top 100 most popular non-quarterly series tagged with `"gdp"`:

```{r fredr_series_tags2}
fredr_tags_series(
  tag_names = "gdp",
  exclude_tag_names = "quarterly",
  order_by = "popularity",
  limit = 100L
)
```