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
— Functionbea_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
BeaData.BeaTable
— Typestruct BeaTable
A BEA table with data and metadata returned from a bea_table
call.
Fields
dataset
: dataset the table was retrieved fromtable_number
: the non-API table numbertable_description
: description of the data contained in the tablemetric
: measurement metric for the data, e.g. index, dollars, etc.units
: billions, millions, etc.line_descriptions
:DataFrame
containing line number descriptionstable_notes
:DataFrame
containing any notes for the tablefrequency
: (M)onthly, (Q)uarterly, or (A)nnualdata_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 tablelast_revised
: date the table was last reviseddata_values
:DataFrame
containing the table data values
Metadata Methods
BeaData.bea_datasets
— Functionbea_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 │
BeaData.bea_parameterlist
— Functionbea_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) │
BeaData.bea_parametervalues
— Functionbea_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) │