BeaData.jl

Installation

At the Julia REPL:

    (@v1.x) pkg> add BeaData

Preliminaries

A valid User ID key is required to use the BEA's API. A User ID can be obtained by registering at the BEA website: https://apps.bea.gov/API/signup/index.cfm.

All metadata and data retrieval functions require your User ID key as a keyword argument. If you plan to use the package frequently, the most convenient option is store your User ID key in a file named .beadatarc in your home directory. The package will look for this file on startup and will assign the key to the global variable USER_ID if it is present.

Supported Datasets

This package currently only works with the BEA datasets that return tables (as opposed to individual data series): NIPA, NIUnderlyingDetail, and FixedAssets.

A full list of the datasets available through the BEA data API can be seen using the bea_datasets method described below.

Retrieving a Table

BeaData.bea_table — Function

bea_table(dataset::String, TableName::String, frequency::String,
    startyear::Int, endyear::Int; user_id = USER_ID) -> BeaTable

Return a BeaTable with data and metadata for TableName. Pass integer value 0 for both startyear and endyear to retrieve all available years for the table. The data values are returned in a DataFrame accessed through the data_values field of the BeaTable struct.

The TableName argument refers to the API TableName parameter value for the requested table. These can be found using the bea_parametervalues method.

Example: to get Table 1.1.6 in the NIPA dataset, quarterly, from 2015 to 2018.

# User ID stored in ~/.beadatarc
julia> nipa116 = bea_table("NIPA", "T10106", "Q", 2015, 2018)
BEA Table
Dataset:   NIPA
Table No.: 1.1.6
Title:     Real Gross Domestic Product, Chained Dollars
Metric:    Chained Dollars
Units:     Billions of chained (2012) dollars
Frequency: Q
Dates:     2015 - 2018
Revised:   August 29, 2019

source

BeaData.BeaTable — Type

struct BeaTable

A BEA table with data and metadata returned from a bea_table call.

Fields

dataset: dataset the table was retrieved from
table_number: the non-API table number
table_description: description of the data contained in the table
metric: measurement metric for the data, e.g. index, dollars, etc.
units: billions, millions, etc.
line_descriptions: DataFrame containing line number descriptions
table_notes: DataFrame containing any notes for the table
frequency: (M)onthly, (Q)uarterly, or (A)nnual
data_startyear: first year of data returned (may differ from what was requested)
data_endyear: last year of data returned (may differ from what was requested)
api_tablename: TableName parameter value for the table
last_revised: date the table was last revised
data_values: DataFrame containing the table data values

source

Metadata Methods

BeaData.bea_datasets — Function

bea_datasets(;user_id::String = USER_ID) -> DataFrame

Return a DataFrame of names and descriptions for datasets accessible through the BEA data API.

Example:

# User ID stored in ~/.beadatarc
julia> bea_datsets();

julia> show(ans[1:3, :])
3×2 DataFrames.DataFrame
│ Row │ DatasetName        │ Description                          │
│     │ String             │ String                               │
├─────┼────────────────────┼──────────────────────────────────────┤
│ 1   │ NIPA               │ Standard NIPA tables                 │
│ 2   │ NIUnderlyingDetail │ Standard NI underlying detail tables │
│ 3   │ MNE                │ Multinational Enterprises            │

source

BeaData.bea_parameterlist — Function

bea_parameterlist(dataset::String; user_id = USER_ID) -> DataFrame

Return a DataFrame of parameter names and attributes for dataset.

Example:

# User ID stored in ~/.beadatarc
julia> bea_parameterlist("NIPA")
5×3 DataFrames.DataFrame. Omitted printing of 1 columns
│ Row │ ParameterName │ ParameterDescription                                           │
│     │ String        │ String                                                         │
├─────┼───────────────┼────────────────────────────────────────────────────────────────┤
│ 1   │ Frequency     │ A - Annual, Q-Quarterly, M-Monthly                             │
│ 2   │ ShowMillions  │ A flag indicating that million-dollar data should be returned. │
│ 3   │ TableID       │ The standard NIPA table identifier                             │
│ 4   │ TableName     │ The new NIPA table identifier                                  │
│ 5   │ Year          │ List of year(s) of data to retrieve (X for All)                │

source

BeaData.bea_parametervalues — Function

bea_parametervalues(dataset::String, param_name:: String;
    user_id = USER_ID) -> DataFrame

Return a DataFrame of permissible values for param_name, with descriptions.

Example:

# User ID stored in ~/.beadatarc
julia> bea_parametervalues("NIPA", "TableName");

julia> show(ans[1:3, :])
3×2 DataFrame
│ Row │ Value  │ Description                                                                              │
│     │ String │ String                                                                                   │
├─────┼────────┼──────────────────────────────────────────────────────────────────────────────────────────┤
│ 1   │ T10101 │ Table 1.1.1. Percent Change From Preceding Period in Real Gross Domestic Product (A) (Q) │
│ 2   │ T10102 │ Table 1.1.2. Contributions to Percent Change in Real Gross Domestic Product (A) (Q)      │
│ 3   │ T10103 │ Table 1.1.3. Real Gross Domestic Product, Quantity Indexes (A) (Q)                       │

source