Author: Sam Boysel
Date: 2021-01-29

# FRED Categories

#### Sam Boysel

#### 2021-01-29

# Introduction

    library(fredr)

This vignette is intended to introduce the user to fredr functions for the Categories endpoint 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.

    fredr_category(category_id = 0L)
    #> # A tibble: 1 x 3
    #>      id name       parent_id
    #>   <int> <chr>          <int>
    #> 1     0 Categories         0

    fredr_category(category_id = 97L)
    #> # A tibble: 1 x 3
    #>      id name    parent_id
    #>   <int> <chr>       <int>
    #> 1    97 Housing         1

## 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.

    fredr_category_children(category_id = 0L)
    #> # A tibble: 8 x 3
    #>      id name                                    parent_id
    #>   <int> <chr>                                       <int>
    #> 1 32991 Money, Banking, & Finance                       0
    #> 2    10 Population, Employment, & Labor Markets         0
    #> 3 32992 National Accounts                               0
    #> 4     1 Production & Business Activity                  0
    #> 5 32455 Prices                                          0
    #> 6 32263 International Data                              0
    #> 7  3008 U.S. Regional Data                              0
    #> 8 33060 Academic Data                                   0

    fredr_category_children(category_id = 1L)
    #> # A tibble: 15 x 3
    #>       id name                                         parent_id
    #>    <int> <chr>                                            <int>
    #>  1 32262 Business Cycle Expansions & Contractions             1
    #>  2 33936 Business Surveys                                     1
    #>  3 32436 Construction                                         1
    #>  4 33940 Emissions                                            1
    #>  5 33955 Expenditures                                         1
    #>  6 33490 Finance Companies                                    1
    #>  7 32216 Health Insurance                                     1
    #>  8    97 Housing                                              1
    #>  9     3 Industrial Production & Capacity Utilization         1
    #> 10 32429 Manufacturing                                        1
    #> 11     6 Retail Trade                                         1
    #> 12 33441 Services                                             1
    #> 13 33492 Technology                                           1
    #> 14 33202 Transportation                                       1
    #> 15 33203 Wholesale Trade                                      1

## 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.

    # Nothing related to the root
    fredr_category_related(category_id = 0L)
    #> # A tibble: 0 x 0

    # What is related to the Employment Cost Index category?
    fredr_category_related(category_id = 4L)
    #> # A tibble: 1 x 3
    #>      id name                                    parent_id
    #>   <int> <chr>                                       <int>
    #> 1    10 Population, Employment, & Labor Markets         0

## 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:

    fredr_category_series(
      category_id = 97L, # Housing
      limit = 100L,
      order_by = "last_updated",
      filter_variable = "frequency",
      filter_value = "Quarterly"
    )
    #> # A tibble: 30 x 16
    #>    id    realtime_start realtime_end title observation_sta… observation_end
    #>    <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #>  1 RHOR… 2021-01-29     2021-01-29   Home… 1965-01-01       2020-07-01
    #>  2 RRVR… 2021-01-29     2021-01-29   Rent… 1956-01-01       2020-07-01
    #>  3 BOAA… 2021-01-29     2021-01-29   Home… 1994-01-01       2020-07-01
    #>  4 ETOT… 2021-01-29     2021-01-29   Hous… 2000-04-01       2020-07-01
    #>  5 RSAH… 2021-01-29     2021-01-29   Home… 1980-01-01       2020-07-01
    #>  6 EOWN… 2021-01-29     2021-01-29   Hous… 2000-04-01       2020-07-01
    #>  7 EVAC… 2021-01-29     2021-01-29   Hous… 2000-04-01       2020-07-01
    #>  8 ERNT… 2021-01-29     2021-01-29   Hous… 2000-04-01       2020-07-01
    #>  9 HOLH… 2021-01-29     2021-01-29   Home… 1994-01-01       2020-07-01
    #> 10 RHVR… 2021-01-29     2021-01-29   Home… 1956-01-01       2020-07-01
    #> # … with 20 more rows, and 10 more variables: frequency <chr>,
    #> #   frequency_short <chr>, units <chr>, units_short <chr>,
    #> #   seasonal_adjustment <chr>, seasonal_adjustment_short <chr>,
    #> #   last_updated <chr>, popularity <int>, group_popularity <int>, notes <chr>

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:

    fredr_category_series(
      category_id = 32992L, # National Accounts
      order_by = "frequency",
      sort_order = "desc",
      tag_names = "usa",
      exclude_tag_names = "gnp"
    )
    #> # A tibble: 4 x 16
    #>   id    realtime_start realtime_end title observation_sta… observation_end
    #>   <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #> 1 NGMP… 2021-01-29     2021-01-29   Tota… 2001-01-01       2019-01-01
    #> 2 RGMP… 2021-01-29     2021-01-29   Tota… 2001-01-01       2019-01-01
    #> 3 PCRG… 2021-01-29     2021-01-29   Tota… 2001-01-01       2017-01-01
    #> 4 QGMP… 2021-01-29     2021-01-29   Tota… 2001-01-01       2019-01-01
    #> # … with 10 more variables: frequency <chr>, frequency_short <chr>,
    #> #   units <chr>, units_short <chr>, seasonal_adjustment <chr>,
    #> #   seasonal_adjustment_short <chr>, last_updated <chr>, popularity <int>,
    #> #   group_popularity <int>, notes <chr>

## 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:

    fredr_category_tags(
      category_id = 6L,
      tag_group_id = "src"
    )
    #> # A tibble: 3 x 6
    #>   name    group_id notes               created           popularity series_count
    #>   <chr>   <chr>    <chr>               <chr>                  <int>        <int>
    #> 1 census  src      Census              2012-02-27 10:18…         80          374
    #> 2 frb stl src      St. Louis Fed       2012-02-27 10:18…         68            4
    #> 3 bea     src      Bureau of Economic… 2012-02-27 10:18…         79            2

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

    fredr_category_tags(
      category_id = 1L,
      search_text = "usa",
      order_by = "popularity",
      sort_order = "desc"
    )
    #> # A tibble: 3 x 6
    #>   name   group_id notes               created            popularity series_count
    #>   <chr>  <chr>    <chr>               <chr>                   <int>        <int>
    #> 1 usa    geo      United States of A… 2012-02-27 10:18:…        100         1626
    #> 2 census src      Census              2012-02-27 10:18:…         80         1626
    #> 3 ga     geo      Georgia (U.S. stat… 2012-02-27 10:18:…         49           32

## 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:

    fredr_category_related_tags(
      category_id = 1L,
      tag_names = "business;monthly",
      exclude_tag_names = "rate",
      order_by = "name"
    )
    #> # A tibble: 10 x 6
    #>    name           group_id notes             created     popularity series_count
    #>    <chr>          <chr>    <chr>             <chr>            <int>        <int>
    #>  1 census         src      "Census"          2012-02-27…         80           10
    #>  2 inventories    gen      ""                2012-02-27…         46            6
    #>  3 mtis           rls      "Manufacturing &… 2012-08-16…         35           10
    #>  4 nation         geot     ""                2012-02-27…         99           10
    #>  5 nsa            seas     "Not Seasonally … 2012-02-27…        100            6
    #>  6 public domain… cc        <NA>             2018-12-17…        100           10
    #>  7 ratio          gen      ""                2012-02-27…         47            4
    #>  8 sa             seas     "Seasonally Adju… 2012-02-27…         88            4
    #>  9 sales          gen      ""                2012-02-27…         63            8
    #> 10 usa            geo      "United States o… 2012-02-27…        100           10