API Reference

State

The primary container for state data tables. There are three fields, all dataframes:

• data: The main data table.
• sets: The sets table, describing the different sets used in the model.
• elements: The elements table, describing the different elements in the model.

absorption(
    state_table::AbstractRegionalTable; 
    column::Symbol = :value, 
    output::Symbol = :value
)

Calculate the absorption for each commodity in each region. The absorption is defined as the sum of:

• Intermediate_Demand
• Other_Final_Demand

Note that absorption is negative.

adjust_by_absorption(
    state_table::State,    
)

Adjust state-level tables by absorption-related components, including:

• Reexports
• Exports
• Household Supply

armington_data(data::T, output = :DataFrame) where T<:AbstractRegionalTable

Extracts Armington-related parameters from the regional data table.

    vcat(
        absorption(data; normalize = true),
        table(data, :Reexport, :National_Demand, :Local_Demand, :Import, :Margin_Demand; normalize = :Use),
        tax_rate(data),
        duty_rate(data)
    )

Aggregate data

• WiNDCRegional.absorption
• WiNDCRegional.tax_rate
• WiNDCRegional.duty_rate

balance_of_payments(
    state_year::AbstractRegionalTable;
    column::Symbol = :value,
    output::Symbol = :value,
    parameter::Symbol = :bopdef,
    minimal::Bool = false
)

Calculate the balance of payments for each commodity in each region. The balance of payments is defined as the sum of:

• Export
• Import

Required Arguments

• state_year::AbstractRegionalTable: The regional data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol = :bopdef: The name of the parameter column.
• minimal::Bool = false: Whether to return a minimal output. If true, only the essential columns are returned: [:region, :year, :parameter, output].

consumption_data(data::T, output = :DataFrame) where T<:AbstractRegionalTable

Extracts consumption-related parameters from the regional data table.

    table(data, :Personal_Consumption; normalize = :Use)

create_reexports(
    state_table::State,
    summary::National,
    raw_data::Dict;
)

Reexports are defined as the negative portion of the difference between total supply and exports.

Depends On

• WiNDCRegional.total_supply
• Exports

Added Parameters

• Reexport with element reexport

Added Sets

• reexport with element reexport in domain col

Aggregate Parameters

Add reexport to Use parameter.

Process

Reexports occur when total supply is less than exports. Calculate reexports as the negative portion of the difference between total supply and exports.

create_regional_demand(
        state_table::State,
        summary::National,
        raw_data::Dict;
    )

Create regional demand (local + national) based on regional purchase coefficients.

Raw Data

• rpc - Regional purchase coefficients loaded using WiNDCRegional.load_regional_purchase_coefficients.

Depends On

• WiNDCRegional.absorption
• WiNDCRegional.total_supply

Added Parameters

• Local_Demand with element local_demand
• National_Demand with element national_demand

Added Sets

• local_demand with element local_demand in domain col
• national_demand with element national_demand in domain col

Aggregate Parameters

Add local_demand and national_demand to Supply parameter.

create_regional_margin_supply(
    state_table::State,
    summary::National,
    raw_data::Dict;
)

Raw Data

• rpc - Regional purchase coefficients loaded using WiNDCRegional.load_regional_purchase_coefficients.

Added Parameters

• Local_Margin_Supply with element local_margin_supply
• National_Margin_Supply with element region_margin_supply
• Margin_Supply with elements local_margin_supply and region_margin_supply

Added Sets

• local_margin_supply with element local_margin_supply in domain parameter
• national_margin_supply with element national_margin_supply in domain parameter

Aggregate Parameters

Add local_margin_supply and national_margin_supply to Margin_Supply and Use parameters.

create_state_table(regional_data_path::String; tol::Float64 = 0.0)

Disaggregate the US WiNDCNational summary-level data into a state-level table, using raw data files located in data_directory. The disaggregation is performed through a sequence of functions, each disaggregating a specific component of the national summary.

Returns a balanced WiNDCRegional State table.

Required Arguments

• regional_data_path::String: Path to the regional.yaml file containing metadata and data file paths needed for disaggregation.

Optional Arguments

• tol::Float64 = 0: Tolerance level for removing small values from the final state table.

Disaggregation Steps

The disaggregation is performed through the following steps:

1. WiNDCRegional.initialize_table
2. WiNDCRegional.disaggregate_intermediate
3. WiNDCRegional.disaggregate_labor_capital
4. WiNDCRegional.disaggregate_output_tax
5. WiNDCRegional.disaggregate_investment_final_demand
6. WiNDCRegional.disaggregate_personal_consumption
7. WiNDCRegional.disaggregate_household_supply
8. WiNDCRegional.disaggregate_government_final_demand
9. WiNDCRegional.disaggregate_foreign_exports
10. WiNDCRegional.create_reexports
11. WiNDCRegional.disaggregate_foreign_imports
12. WiNDCRegional.disaggregate_margin_demand
13. WiNDCRegional.disaggregate_duty
14. WiNDCRegional.disaggregate_tax
15. WiNDCRegional.create_regional_demand
16. WiNDCRegional.create_regional_margin_supply

disaggregate_by_shares(
        summary::WiNDCNational.National,
        disaggregate::DataFrame,
        parameter::Vector{Symbol};
        domain = :commodity,
    )

disaggregate_by_shares(
        summary::WiNDCNational.National,
        disaggregate::DataFrame,
        parameter::Symbol;
        domain = :commodity,
    )

Disaggregate the national-level parameter from the summary data to the regional level using shares from the disaggregate DataFrame.

The disaggregate DataFrame should contain the columns:

• :year: The year of the data.
• :state: The state identifier.
• :naics: The industry code.
• :value: The share value for disaggregation.
• :name: The name of the industry or sector.

The function returns a DataFrame with the disaggregated values for each state and industry code.

This function will identify values in summary that are not present in disaggregate and will disaggreagte by equal shares.

disaggregate_duty(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the duty from the national summary into state-level using national level duty rates and total imports by state.

Depends On

• Imports

Added Parameters

• Duty with element duty

Aggregate Parameters

Add duty to Supply parameter.

Process

Assume equal duty rates across all states. Calculate state-level duty by multiplying state-level imports by the national duty rate.

disaggregate_foreign_exports(
        state_table::State,    
        summary::National,
        raw_data::Dict;
    )

Disaggregate the foreign exports from the national summary into state-level using BEA GSP data and trade shares.

Raw Data

• gdp - State GDP data (SAGDP2) loaded using WiNDCRegional.load_state_gdp.
• trade_shares - Trade shares data loaded using WiNDCRegional.load_trade_shares.

Added Parameters

• Export with element export

Aggregate Parameters

Add export to Use, Final_Demand, and Export parameters.

Process

Use trade shares data to disaggregate exports where available. For commodities without trade share data, use state GDP data to disaggregate exports by shares.

disaggregate_foreign_imports(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the foreign imports from the national summary into state-level using absorption.

Depends On

• absorption

Added Parameters

• Import with element import

Aggregate Parameters

Add import to Supply parameter.

Process

Use the WiNDCRegional.disaggregate_by_shares function on the domain commodity to disaggregate imports using absorption data as shares.

disaggregate_government_final_demand(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the government final demand from the national summary into state-level using Census SGF data. Also aggregates all government final demand to a single element govern, updates the elements table accordingly.

Raw Data

• sgf - State Government Finances data loaded using WiNDCRegional.load_state_finances.

Added Parameters

• Government_Final_Demand with element government_final_demand

Added Sets

• government_final_demand with element govern in domain col

Aggregate Parameters

Add government_final_demand to Use, Other_Final_Demand, and Final_Demand parameters.

Process

Use the WiNDCRegional.disaggregate_by_shares function on the domain commodity to disaggregate government final demand using Census SGF data as shares.

The data is then grouped by row, year, parameter, and region to aggregate all summary-level government final demand elements into a single element govern.

disaggregate_household_supply(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the household supply from the national summary into state-level using BEA PCE data.

Raw Data

• pce - Personal Consumption Expenditure data loaded using WiNDCRegional.load_pce_data.

Added Parameters

• Household_Supply with element household_supply

Aggregate Parameters

Add household_supply to Supply parameters.

Process

Use the WiNDCRegional.disaggregate_by_shares function on the domain commodity to disaggregate household supply using BEA PCE data as shares.

disaggregate_intermediate(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the intermediate demand and supply from the national summary into state-level using BEA GSP data.

Raw Data

• gdp - State GDP data (SAGDP2) loaded using WiNDCRegional.load_state_gdp.

Added Parameters

• Intermediate_Demand with element intermediate_demand
• Intermediate_Supply with element intermediate_supply

Aggregate Parameters

Add intermediate_demand to Use parameter and intermediate_supply to Supply parameter.

Process

Use the WiNDCRegional.disaggregate_by_shares function on the domain sector to disaggregate intermediate demand and supply using state GDP data as shares.

disaggregate_investement_final_demand(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the investment final demand from the national summary into state-level using BEA GSP data. Also aggregates all investment final demand to a single element invest, updates the elements table accordingly.

Raw Data

• gdp - State GDP data (SAGDP2) loaded using WiNDCRegional.load_state_gdp.

Added Parameters

• Investment_Final_Demand with element investment_final_demand

Added Sets

• investment_final_demand with element invest in domain col

Aggregate Parameters

Add investment_final_demand to Use, Other_Final_Demand, and Final_Demand parameters.

Process

Use the WiNDCRegional.disaggregate_by_shares function on the domain commodity to disaggregate investment final demand using state GDP data as shares.

The data is then grouped by row, year, parameter, and region to aggregate all summary-level investment final demand elements into a single element invest.

disaggregate_labor_capital(
        state_table::State,    
        summary::National,
        raw_data::Dict;
    )

Disaggregate the labor and capital demand from the national summary into state-level using BEA GSP data.

Raw Data

All data is loaded using WiNDCRegional.load_state_gdp.

• gdp - State GDP data (SAGDP2)
• labor - State labor data (SAGDP4)
• capital - State capital data (SAGDP7)
• tax - State tax data (SAGDP6)
• subsidy - State subsidy data (SAGDP5)

Added Parameters

• Labor_Demand with element labor_demand
• Capital_Demand with element capital_demand

Aggregate Parameters

Add labor_demand and capital_demand to Value_Added and Use parameters.

disaggregate_margin_demand(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the margin demand from the national summary into state-level using absorption.

Depends On

• absorption

Added Parameters

• Margin_Demand with element margin_demand

Aggregate Parameters

Add margin_demand to Supply parameter.

Process

Use the WiNDCRegional.disaggregate_by_shares function on the domain commodity to disaggregate margin demand using absorption data as shares.

disaggregate_output_tax(
    state_table::State,    
    summary::National,
    data_directory::String
)

Disaggregate the output tax from the national summary into state-level using national level tax rates and total output by state.

Depends On

• Intermediate Supply
• Summary output tax rate

Added Parameters

• Output_Tax with element output_tax

Aggregate Parameters

Add output_tax to Use set.

Process

Assume equal tax rates across all states. Calculate state-level output tax by multiplying state-level intermediate supply by the national output tax rate.

disaggregate_personal_consumption(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the personal consumption expenditure by shares from the national summary into state-level using BEA PCE data.

Raw Data

• pce - Personal Consumption Expenditure data loaded using WiNDCRegional.load_pce_data.

Added Parameters

• Personal_Consumption with element personal_consumption

Aggregate Parameters

Add personal_consumption to Use, Other_Final_Demand, and Final_Demand parameters.

Process

Use the WiNDCRegional.disaggregate_by_shares function on the domain commodity to disaggregate personal consumption using BEA PCE data as shares.

disaggregate_tax(
    state_table::State,    
    summary::National,
    raw_data::Dict;
)

Disaggregate the tax from the national summary into state-level using BEA GSP data. The resulting tax will be inclusive of subsidies, which is a change from the summary level data.

Depends On

• WiNDCRegional.absorption
• Summary absorption tax rate

Added Parameters

• Tax with element tax

Aggregate Parameters

Add tax to Supply parameters.

Process

The absorption tax rate is calculated inclusive of subisidies at the national level. Assume equal tax rates across all states. The state-level tax is calculated by multiplying the state-level absorption by the national absorption tax rate.

disposition_data(data::T, output = :DataFrame) where T<:AbstractRegionalTable

Extracts disposition-related parameters from the regional data table.

    vcat(
        regional_local_supply(data),
        netports(data),
        total_supply(data),
        regional_national_supply(data)
        )

Aggregate Data

• WiNDCRegional.regional_local_supply
• WiNDCRegional.netports
• WiNDCRegional.total_supply
• WiNDCRegional.regional_national_supply

dutyrate( statetable::AbstractRegionalTable; column::Symbol = :value, output::Symbol = :value, parameter = :duty_rate, minimal::Bool = false )

Calculate the duty rate for each commodity in each region. The duty rate is defined as the ratio of Duty to Import.

Required Arguments

• state_table::AbstractRegionalTable: The regional data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol =:duty_rate`: The name of the parameter column.
• minimal::Bool = false: Whether to return a minimal output. If true, only the essential columns are returned: [:col, :region, :year, :parameter, output].

extend_data(X::DataFrame, column::Symbol, old_value, new_value)

Extend data from X by copying rows where column equals old_value to new rows where column equals new_value. This is used, for example, the maximum year is 2023, but we need to extend to 2024 by copying 2023 data.

The function takes four arguments:

• X::DataFrame: The dataframe to append.
• column::Symbol: The column to search for the old value.
• exisiting_data: The base data to use for the new values
• new_data: The name of the new data.

household_adjustment(
    state_year::AbstractRegionalTable;
    column::Symbol = :value,
    output::Symbol = :value,
    parameter::Symbol = :house_adjustment,
    minimal::Bool = false
)

Calculate the household adjustment for each commodity in each region. The household adjustment is defined as the sum of:

• Other_Final_Demand
• balance_of_payments
• Value_Added
• Household_Supply
• Output_Tax
• Tax
• Duty

Required Arguments

• state_year::AbstractRegionalTable: The regional data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol = :house_adjustment: The name of the parameter column.
• minimal::Bool = false: Whether to return a minimal output. If true, only the essential columns are returned: [:row, :region, :year, :parameter, output].

initialize_table(summary::National)

Create an empty State table structure based on the sets and elements of the provided National summary.

Add one set, State, containing all US states. The states are loaded using the WiNDCRegional.load_state_fips function.

Each disaggregation function will add new parameters and elements as needed.

Sets with Elements Preserved

• capital_demand
• commodity
• duty
• export
• import
• labor_demand
• margin
• output_tax
• personal_consumption
• sector
• tax
• trade
• transport
• year

Aggregate Parameters

These parameters are kept, but all elements are removed.

• Other_Final_Demand
• Use
• Supply
• Final_Demand
• Value_Added

labor_shares(
    summary::National,
    raw_data::Dict;
)

Compute the share of total value added (labor + capital) attributed to labor for each region, sector, and year.

Returns a DataFrame with columns: year, region, col (sector), and value (labor share).

Required Arguments

• summary::National: A National object containing the national summary data.
• raw_data::Dict: A dictionary containing the raw data DataFrames.

Raw Data Used

All data is loaded with load_state_gdp, the dictionary should contain the following keys:

• :gdp - SAGDP2
• :labor - SAGDP4
• :capital - SAGDP7
• :tax - SAGDP6
• :subsidy - SAGDP5

Motivation

The captial data provided by the BEA has unavoidable negative values for some years, sectors, and regions. To address this, we compute labor shares by reconciling the reported GDP data with GDP computed from GSP components (labor, capital, tax, subsidy). We then use a least squares optimization approach to estimate labor shares that are consistent with both the national-level labor shares and the regional GDP data.

Data Source

This data can be downloaded from the BEA website, select Gross Domestic Product (GDP) by State and download the SAGDP data.

load_faf_base(
    path::String,
    state_fips::DataFrame,
    faf_map::DataFrame;
    cols_to_keep = [
        :fr_orig,
        :dms_origst,
        :dms_destst,
        :fr_dest,
        :trade_type,
        :sctg2,
    ],
    regex_cols_to_keep = r"^value_(\d{4})$",
    max_year = 2023,
)

The FAF provides two files, one with data from 2017 onward, and one with reprocessed data from 1997-2012. This function provides the common loading logic.

load_faf_data(
    state_path::String,
    reprocessed_path::String,
    state_fips::DataFrame,
    faf_map::DataFrame;
    cols_to_keep = [
        :fr_orig,
        :dms_origst,
        :dms_destst,
        :fr_dest,
        :trade_type,
        :sctg2,
    ],
    regex_cols_to_keep = r"^value_(\d{4})$",
    max_year = 2023,
)

Load the two necessary FAF files and aggregate to demand. The returned DataFrame has columns:

• destination - FIPS code of destination state
• year - Year of the trade flow
• naics - NAICS code of the traded good
• local - And indicator on if the flow is local (within state) or national (between states)
• value - Value of the traded good in millions of USD

The returned DataFrame has data for all years 1997 to max_year. The reprocessed data only has data on a five year basis (1997, 2002, 2007, 2012), the intermediate years uses the data from the closest available year.

Data Source

The Frieght Analysis Framework (FAF) data can be downloaded from the BTS website. We use two data files:

• The regional database, or FAF5.7.1_State.csv as of December 2025, which contains data from 2017 onward.
• The reprocessed data file, or FAF5.7.1_Reprocessed.csv as of December 2025, which contains data from 1997 to 2012 on a five-year basis.

load_faf_map(; 
        path = joinpath(@__DIR__,  "data", "faf_map.csv"),
        keep_cols::Vector{Symbol} = [:sctg2, :naics]
    )

Load the FAF to NAICS mapping file. Optionally keep only a subset of columns, by specifying the keep_cols argument.

Returns a DataFrame with the specified columns. The naics column is converted to a Symbol.

Optional Arguments

• path::String: Path to the FAF mapping CSV file.
• keep_cols::Vector{Symbol}: Columns to keep from the CSV file. Default is

[:sctg2, :naics].

load_industry_codes(;
        path = joinpath(@__DIR__, "data", "industry_codes.csv"),
    )

Load a CSV file containing industry codes. The default path is set to "data/industry_codes.csv" relative to this file's directory.

Returns a DataFrame with two columns, LineCode and naics. The naics column is converted to a Symbol and and missing values are dropped.

Optional Arguments

• path::String: Path to the industry codes CSV file.

load_map_data(map_dictionary::Dict)

Load map data specified in the metadata:maps section of the regional.yaml file. Returns a dictionary of DataFrames, with keys corresponding to the map types.

If the paths are not speicifed in WiNDCRegional.load_regional_yaml, the default maps will be loaded.

Required Arguments

• map_dictionary::Dict: A dictionary with keys the name of the map and values the path to the map data file. If the value is nothing, the default map will be loaded.

Default Loading Functions

• state_map - WiNDCRegional.load_state_fips
• gdp_map - WiNDCRegional.load_industry_codes
• pce_map - WiNDCRegional.load_pce_map
• sgf_map - WiNDCRegional.load_sgf_map
• sgf_states_map - WiNDCRegional.load_sgf_states
• trade_map - WiNDCRegional.load_usatrade_map
• faf_map - WiNDCRegional.load_faf_map

function load_pce_data(
    path::String,
    name::String;
    state_fips::DataFrame = load_state_fips(),
    pce_map::DataFrame = load_pce_map(),
)

Load the Personal Consumption Expenditures (PCE) data.

Required Arguments

• path::String: Path to the PCE CSV file.
• name::String: Name to assign to the loaded data, e.g. the state name.

Optional Arguments

• state_fips::DataFrame: load_state_fips DataFrame mapping state FIPS codes to state abbreviations.
• pce_map::DataFrame: load_pce_map DataFrame mapping PCE LineCodes to NAICS codes.

Data Source

This data can be downloaded from the BEA website, select Personal Consumption Expenditures (PCE) by State and download the PCE data.

load_pce_map(;
        path = joinpath(@__DIR__, "data", "pce_map.csv"),
    )

Load the PCE to NAICS mapping file. The default path is set to data/pce_map.csv relative to this file's directory.

Returns a DataFrame with four columns: Line Code, description_pcs, naics, and description. It is recommended you mirror this structure if you provide your own mapping file.

Optional Arguments

• path::String: Path to the PCE mapping CSV file.

load_raw_data(
        summary::National,
        data_info::Dict, 
        data_directory::String, 
        maps::Dict{Symbol, DataFrame}
    )

Load data files specified in regional.yaml needed for disaggregation of the US WiNDCNational summary into state-level WiNDCRegional table.

Returns a dictionary of DataFrames, with keys corresponding to key in the data section of regional.yaml.

Required Arguments

• summary::National: The national summary WiNDCNational table.
• data_info::Dict: The data section of the regional.yaml file.
• data_directory::String: The base directory where data files are located. This is specified in the metadata:data_directory field of regional.yaml.
• maps::Dict{Symbol, DataFrame}: A dictionary of mapping DataFrames loaded using WiNDCRegional.load_map_data.

Data Loading Functions

• state_gdp - All values - WiNDCRegional.load_state_gdp
• pce - WiNDCRegional.load_pce_data
• sgf - WiNDCRegional.load_state_finances
• trade_shares
  • exports and imports - WiNDCRegional.load_usa_raw_trade_data
  • ag_time_series - WiNDCRegional.load_usda_agricultural_flow
  • trade shares - WiNDCRegional.load_trade_shares
• rpc - WiNDCRegional.load_regional_purchase_coefficients

load_regional_purchase_coefficients(
    summary::WiNDCNational.National,
    state_path::String,
    reprocessed_path::String,
    data_directory::String;
    adjusted_demand = Dict{Symbol, Float64} = Dict(),
    state_fips::DataFrame = load_state_fips(),
    faf_map::DataFrame = load_faf_map(),
    cols_to_keep = [
        :fr_orig,
        :dms_origst,
        :dms_destst,
        :fr_dest,
        :trade_type,
        :sctg2,
    ],
    regex_cols_to_keep = r"^value_(\d{4})$",
    max_year = elements(summary, :year) |> x->maximum(x[!,:name]),
    )

The regional purchase coefficients are used to determine the mixture of domestic vs. national demand in the absorption market. The coefficients are calculated based on the FAF data and the commodity data. The returned DataFrame has columns:

• state - FIPS code of the state
• year - Year of the coefficient
• naics - NAICS code of the good
• rpc - Regional purchase coefficient, between 0 and 1

The computation has several steps:

1. Load the FAF data using load_faf_data to get trade flows.
2. Identify non-trade goods, which are goods that do not appear in the FAF data. Pin the RPC to be the average over the traded goods.
3. Compute the RPC as local / (local + national)
4. Apply any adjusted demand values provided in the adjusted_demand dictionary.

Arguments

• summary: The national summary data, used to identify non-trade goods.
• state_path: Path to the FAF data file for state-level data (2017 onward).
• reprocessed_path: Path to the FAF data file for reprocessed data (1997 to 2012).
• data_directory: Base directory for the data files.

Optional Arguments

• adjusted_demand: A dictionary mapping NAICS codes to adjusted RPC values. If a NAICS code is present in this dictionary, the corresponding RPC value will be used instead of the computed value. Default is an empty dictionary.
• state_fips: DataFrame containing state FIPS codes. Defaults to loading from common files.
• faf_map: DataFrame mapping FAF SCTG codes to NAICS codes. Defaults to loading from common files.
• cols_to_keep: Columns to keep from the FAF data. Defaults to a predefined list of columns.
• regex_cols_to_keep: Regular expression to match columns to keep from the FAF data. Defaults to a predefined regular expression.
• max_year: Maximum year to include in the data. Defaults to the maximum year in the summary data.

load_regional_yaml(path::String; file_name::String = "regional.yaml")

Load a YAML file containing regional configuration data. Ensure the file is formatted correctly with proper field names and structure.

Arguments

• path::String: The directory path where the YAML file is located.

Optional Arguments

• file_name::String: The name of the YAML file. Default is "regional.yaml".

Returns

A dictionary containing the parsed YAML data.

Fields

metadata

• title::String: Title of the regional data configuration.
• description::String: Description of the regional data configuration.
• data_directory::String: (Optional) Base directory for regional data files, if not provided, defaults to the path argument.
• maps: This specifies the mapping files. By default, the maps have not values indicating that the default mapping files included with the package should be used. If the user wishes to provide custom mapping files, they can specify the paths here.

data

Specify paths to various data files needed for regional disaggregation.

load_sgf_map(;
        path = joinpath(@__DIR__, "data", "sgf_map.csv"),
        keep_cols::Vector{Symbol} = [:naics, :sgf_code]
    )

Load the SGF to NAICS mapping file. Optionally keep only a subset of columns, by specifying the keep_cols argument.

Returns a DataFrame with the specified columns. All data is returned as Strings.

Optional Arguments

• path::String: Path to the SGF mapping CSV file.
• keep_cols::Vector{Symbol}: Columns to keep from the CSV file. Default is

[:naics, :sgf_code].

load_sgf_states(;
        path = joinpath(@__DIR__, "data", "sgf_states.csv"),
    )

Load the SGF states mapping file. The default path is set to data/sgf_states.csv relative to this file's directory.

Returns a DataFrame with two columns: code and state. Both columns are converted to Strings.

Optional Arguments

• path::String: Path to the SGF states CSV file.

load_state_finances(
    file_pattern::Regex,
    directory_path::String;
    sgf_map::DataFrame = WiNDCRegional.load_sgf_map(),
    sgf_states::DataFrame = WiNDCRegional.load_sgf_states(),
    replacement_data::Dict = Dict()
    )

Load state government finance data that matches the file pattern in the given directory path.

Required Arguments

• file_pattern::Regex: A regex pattern to match the filenames, typically of the form ^(?<year>\d{2})(state|data)35.txt$
• directory_path::String: Location of the data files.

Optional Arguments

• sgf_map::DataFrame: A dataframe mapping SGF codes to NAICS codes. Default is WiNDCRegional.load_sgf_map().
• sgf_states::DataFrame: A dataframe mapping FIPS codes to state names. Default is WiNDCRegional.load_sgf_states().
• replacement_data::Dict: A dictionary of replacement data to append to the dataframe. The keys are column names, and the values are dictionaries mapping new data names to existing data names. The replacement is done using WiNDCRegional.extend_data.

Data Source

The data can be downloaded from Census.gov. We need this data from 1997 onward. There does not appear to be a bulk download option, so each file must be downloaded manually.

These files are heavily encoded TXT files. For reference, here are the first few lines of the 2023 data file (23state35.txt):

load_state_fips(;
        path = joinpath(@__DIR__, "data", "state_fips.csv"),
        cols_to_keep = [:fips, :state]
    )

Load a CSV file containing state FIPS codes and state names. The default path is set to data/state_fips.csv relative to this file's directory. You can specify which columns to keep using the cols_to_keep argument.

Returns a DataFrame with the specified columns as Strings.

Optional Arguments

• path::String: Path to the state FIPS CSV file.
• cols_to_keep::Vector{Symbol}: Columns to keep from the CSV file. Default is [:fips, :state].

It is recommended to keep the columns :fips and :state for proper mapping.

load_state_gdp(
    path::String, 
    name::String;
    state_fips::DataFrame = load_state_fips(),
    industry_codes::DataFrame = load_industry_codes(),
    )

Load SAGDP data.

Required Arguments

• path::String: Path to the SAGDP CSV file.
• name::String: Name to assign to the loaded data, e.g. gdp.

Optional Arguments

• state_fips::DataFrame: DataFrame mapping state FIPS codes to state abbreviations.
• industry_codes::DataFrame: DataFrame mapping BEA industry codes to NAICS codes.

By default, we use the default maps provided by load_state_fips() and load_industry_codes(). However, any mapping DataFrame with the same structure can be provided.

Data Source

This data can be downloaded from the BEA website, select Gross Domestic Product (GDP) by State and download the SAGDP data.

load_trade_shares(
    exports::DataFrame,
    imports::DataFrame,
    usda_agricultural_flow::DataFrame;
    agricultural_code = Symbol("111CA"),
    base_year::Int = 1997
)

Use exports, imports and usda agricultural flow data to calculate the foreign flow of goods.

Required Arguments

• exports::DataFrame: Export data from load_usa_raw_trade_data.
• imports::DataFrame: Import data from load_usa_raw_trade_data.
• usda_agricultural_flow::DataFrame: Agricultural flow data from load_usda_agricultural_flow.

Optional Arguments

• agricultural_code::Symbol: The NAICS code for the agricultural commodity. Default is :111CA.
• base_year::Int: The base year for backfilling missing years. Default is 1997, the first year of summary data.

Loading Process

First we calculate the trade shares for each state, commodity, flow, and year. This is given by:

\[\frac{V}{\sum_{{\rm state}} V}\]

There are years with no trade data for certain commodities. We use the yearly region share to set a default value for each state and commodity/flow pair. The yearly region share is defined by:

\[\frac{sum_{{\rm year}} V}{sum_{{\rm state}}\left(sum_{{\rm year}} V\right)}\]

These two values are combined such that if there is no trade data for a given year, the default value is used instead. We then remove all values where with naics code agricultural_code and flow exports from the data, and append the USDA agricultural flow data.

Finally, we back fill missing years for 1997-2001 using the next available year's data. Note that the minimum year for each state/commodity/flow combination is used to determine which years need to be back filled, with a maximum year of 2002.

load_usa_raw_trade_data(
    path::String,
    flow::String;
    value_col::Symbol = flow == "exports" ? :Total_Exports_Value_US_ : :Customs_Value_Gen_US_,
    state_fips::DataFrame = load_state_fips(),
    usatrade_map::DataFrame = load_usatrade_map(),
)

Load data exported from the USA Trade online portal. The input flow should be either "exports" or "imports".

The value_col should be either :Total_Exports_Value_US_ or :Customs_Value_Gen_US_ depending on whether you are loading export or import data.

This will return a normalized DataFrame with columns :year, :state, :naics, :value, and :flow.

Data Source

This data is available from the USA Trade Online portal. This requires a log-in. For both Imports and Exports we want NAICS data. When selecting data, we want every state (this is different that All States), the most disaggregated commodities (third level), and for Exports we want World Total and for Imports we want both World Total and Canada in the Countries column.

load_usatrade_map(;
        path = joinpath(@__DIR__, "data", "usatrade_map.csv"),
        keep_cols::Vector{Symbol} = [:naics, :naics4]
    )

Load the USA Trade to NAICS mapping file. Optionally keep only a subset of columns, by specifying the keep_cols argument.

Returns a DataFrame with the specified columns. The naics and naics4 columns are converted to Symbols.

Optional Arguments

• path::String: Path to the USA Trade mapping CSV file.
• keep_cols::Vector{Symbol}: Columns to keep from the CSV file. Default is

[:naics, :naics4].

load_usda_agricultural_flow(
        path::String,
        sheet::String,
        range::String; 
        agriculture_code = Symbol("111CA"),
        flow::String = "exports"
    )

Load additional agricultural trade flow data from USDA. This data is used to supplement the USA Trade data for the agricultural_code.

Returns a DataFrame with columns :year, :state, :naics, :value, and :flow.

Required Arguments

• path::String: Path to the Excel file.
• sheet::String: Sheet name in the Excel file.
• range::String: Cell range in the sheet to read.

Optional Arguments

• agriculture_code::Symbol: The NAICS code for the agricultural commodity. Default is :111CA.
• flow::String: The trade flow type, either exports or imports. Default is exports.

Data Source

This loads the file Commodity_detail_by_state_cy.xlsx. This is a very fragile link that may change over time. If you find this link is broken, raise an issue on the WiNDCRegional GitHub repository.

margin_balance(
    data::AbstractRegionalTable; 
    column::Symbol = :value, 
    output::Symbol = :value,
    parameter::Symbol = :margin_balance,
    minimal::Bool = true
)

Calculate the margin balance condition. For each margin, the margin balance condition is defined as the sum of the following parameters:

• Margin_Supply
• Margin_Demand

Required Arguments

• data::AbstractRegionalTable: The national data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol =:margin_balance`: The name of the parameter column.
• minimal::Bool = true: Whether to return a minimal output. If true, only the essential columns are returned: [:col, :year, :parameter, output].

Output

Returns a DataFrame with columns [:row, :col, :year, :parameter, output], where output is the renamed column column. Note that :col is filled with :mb and :parameter is filled with parameter.

margin_supply_demand(data::T, output = :DataFrame) where T<:AbstractRegionalTable

Extracts margin supply and demand parameters from the regional data table.

    table(data, :Margin_Demand, :Margin_Supply; normalize = :Use)

market_clearance(
    data::AbstractRegionalTable; 
    column::Symbol = :value, 
    output::Symbol = :value,
    parameter::Symbol = :market_clearance,
    minimal::Bool = true
)

Calculate the market clearance condition. For each commodity, the market clearance condition is defined as the sum of the following parameters:

• Intermediate_Demand
• Final_Demand
• Intermediate_Supply
• Household_Supply
• Margin_Supply
• Margin_Demand
• Imports
• Tax
• Duty
• Subsidies

Required Arguments

• data::AbstractRegionalTable: The national data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol =:market_clearance`: The name of the parameter column.
• minimal::Bool = true: Whether to return a minimal output. If true, only the essential columns are returned: [:row, :year, :parameter, output].

Output

Returns a DataFrame with columns [:row, :col, :year, :parameter, output], where output is the renamed column column. Note that :col is filled with :mc and :parameter is filled with parameter.

netports(
    state_year::AbstractRegionalTable;
    column::Symbol = :value,
    output::Symbol = :value,
    parameter::Symbol = :netport,
    minimal::Bool = false
)

Calculate the netports for each commodity in each region. The netport is defined as the difference between Export and Reexport.

output_tax_rate(
        state_table::AbstractRegionalTable; 
        column::Symbol = :value, 
        output::Symbol = :value,
        parameter = :output_tax_rate,
        minimal::Bool = false
    )

Calculate the output tax rate for each commodity in each region. The output tax rate is defined as the ratio of Output_Tax to the sum over commodities of Intermediate_Supply.

Required Arguments

• state_table::AbstractRegionalTable: The regional data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol =:outputtaxrate`: The name of the parameter column.
• minimal::Bool = false: Whether to return a minimal output. If true, only the essential columns are returned: [:col, :region, :year, :parameter, output].

parse_value_by_unit(unit::String, value::Real)

Want values to be in billions of dollars

regional_local_supply(
    state_year::AbstractRegionalTable;
    column::Symbol = :value,
    output::Symbol = :value,
    parameter::Symbol = :region_local_supply,
    minimal::Bool = false
)

Calculate the regional local supply for each commodity in each region. The regional local supply is defined as the sum of Local_Margin_Supply and Local_Demand.

regional_model(state_table::State; year = 2024)

Constructs a regional MPSGE model based on the provided state-level data table.

Arguments

• state_table::State: A state-level data table containing the necessary parameters for the regional model.

Optional Arguments

• year::Int = 2024: The year for which the model is being constructed. This determines which year's data from the state table will be used.

Returns

An MPSGEModel object representing the regional model.

Paramters

This model includes the following parameters:

• OTR[r=states, s=sectors]: The output tax rate applied to sectoral outputs in each state.
• TR[r=states, g=commodities]: The tax rate applied to commodities in each state.
• DR[r=states, g=commodities]: The duty rate applied to imported commodities in each state.

If the model is denoted M, these parameters can be accessed as M[:OTR], M[:TR], and M[:DR].

Variables

Sectors

• Y[r=states, s=sectors]: Sectoral production in each state.
• X[r=states, g=commodities]: Commodity disposition in each state.
• A[r=states, g=commodities]: Commodity absorption in each state.
• C[r=states]: Aggregate final demand in each state.
• MS[r=states, m=margins]: Margin supply in each state.

Commodities

• PA[r=states, g=commodities]: Regional market (input) prices in each state.
• PY[r=states, g=commodities]: Regional market (output) prices in each state.
• PD[r=states, g=commodities]: Local market prices in each state.
• PN[g=commodities]: National market prices.
• PL[r=states]: Wage rates in each state.
• PK[r=states, s=sectors]: Rental rates of capital in each state.
• PM[r=states, m=margins]: Margin prices in each state.
• PC[r=states]: Consumer price index in each state.
• PFX: Foreign exchange rate.

Consumer

• RA[r=states]: Representative agent in each state.

Production Blocks

Y

WiNDCRegional.sectoral_output

sectoral_output(state_year; output = :DefaultDict) |> Q->
@production(M, Y[r=states, s=sectors], [t=0, s=0, va=>s=1], begin
    @output(PY[r,g=commodities], Q[g, s, r, :intermediate_supply],                     t, taxes = [Tax(RA[r], M[:OTR][r,s])], reference_price = 1-Q[:otr, s, r, :output_tax_rate])
    @input(PA[r, g=commodities], Q[g, s, r, :intermediate_demand],                     s)
    @input(PL[r],            sum(Q[l, s, r, :labor_demand] for l in labor_demand),     va)
    @input(PK[r, s],         sum(Q[k, s, r, :capital_demand] for k in capital_demand), va)
end)

X

WiNDCRegional.disposition_data

disposition_data(state_year; output = :DefaultDict) |> Q->
@production(M, X[r=states, g=commodities], [s=0, t=4], begin
    @output(PFX,      Q[g, r, :netport],                t)
    @output(PN[g],    Q[g, r, :region_national_supply], t)
    @output(PD[r, g], Q[g, r, :region_local_supply],    t)
    @input(PY[r, g],  Q[g, r, :total_supply],           s)
end)

A

WiNDCRegional.armington_data

armington_data(state_year; output = :DefaultDict) |> Q-> 
@production(M, A[r=states, g=commodities], [t=0, s=0, dm => s = 2, d=>dm=4], begin
    @output(PA[r, g],        Q[g, :abs, r, :absorption],                  t, taxes = [Tax(RA[r], M[:TR][r,g])], reference_price = 1 - Q[g, :tr, r, :tax_rate])
    @output(PFX,             Q[g, :reexport, r, :reexport],               t)
    @input(PN[g],            Q[g, :national_demand, r, :national_demand], d)
    @input(PD[r, g],         Q[g, :local_demand, r, :local_demand],       d)
    @input(PFX,          sum(Q[g, i, r, :import] for i in imports),       dm, taxes = [Tax(RA[r], M[:DR][r,g])], reference_price = 1 + Q[g, :dr, r, :duty_rate])
    @input(PM[r, m=margins], Q[g, m, r, :margin_demand],                  s)
end)

MS

WiNDCRegional.margin_supply_demand

margin_supply_demand(state_year; output = :DefaultDict) |> Q->
@production(M, MS[r=states, m=margins], [t=0, s=0], begin
    @output(PM[r, m],        sum(Q[g, m, r, :margin_demand] for g in commodities), t)
    @input(PN[g=commodities],    Q[g, m, r, :national_margin_supply],              s)
    @input(PD[r, g=commodities], Q[g, m, r, :local_margin_supply],                 s)
end)

C

WiNDCRegional.consumption_data

consumption_data(state_year; output = :DefaultDict) |> Q->
@production(M, C[r=states], [t=0, s=1], begin
    @output(PC[r],           sum(Q[g, r, :personal_consumption] for g in commodities), t)
    @input(PA[r, g=commodities], Q[g, r, :personal_consumption],                       s)
end)

Demand Blocks

RA

WiNDCRegional.representative_agent_data

@demand(M, RA[r=states], begin
    @final_demand(PC[r],              sum(Q[g, s, r, :personal_consumption] for g in commodities, s in personal_consumption))
    @endowment(PY[r, g=commodities],  sum(Q[g, s, r, :household_supply] for s in personal_consumption))
    @endowment(PFX,                       Q[:bopdef, :bopdef, r, :bopdef] + Q[:hhadj, :hhadj, r, :house_adjustment])
    @endowment(PA[r, g=commodities],     -Q[g, :govern, r, :government_final_demand] -Q[g, :invest, r, :investment_final_demand])
    @endowment(PL[r],                 sum(Q[g, s, r, :labor_demand] for g in labor_demand, s in sectors))
    @endowment(PK[r, s=sectors],      sum(Q[g, s, r, :capital_demand] for g in capital_demand))
end)

regional_national_supply(
    state_year::AbstractRegionalTable;
    column::Symbol = :value,
    output::Symbol = :value,
    parameter::Symbol = :region_national_supply,
    minimal::Bool = false
)

Calculate the regional national supply for each commodity in each region. The regional national supply is defined as total supply minus net exports minus regional local supply.

representative_agent_data(data::T, output = :DataFrame) where T<:AbstractRegionalTable

Extracts representative agent-related parameters from the regional data table.

    vcat(
        table(data,
            :Personal_Consumption,
            :Household_Supply,
            :Other_Final_Demand,
            :Value_Added;
            normalize = :Use
            ) ,
        household_adjustment(data),
        balance_of_payments(data)
    )

Aggregate Data

• WiNDCRegional.household_adjustment
• WiNDCRegional.balance_of_payments

sectoral_output(data::T, output = :DataFrame) where T<:AbstractRegionalTable

Extracts sectoral output-related parameters from the regional data table.

vcat(
    table(data, 
        :Intermediate_Supply, 
        :Intermediate_Demand, 
        :Labor_Demand, 
        :Capital_Demand;
        normalize = :Use
        ),
    output_tax_rate(data)
    )

tax_rate(
    state_table::AbstractRegionalTable; 
    column::Symbol = :value, 
    output::Symbol = :value,
    parameter = :tax_rate,
    minimal::Bool = false
)

Calculate the tax rate for each commodity in each region. The tax rate is defined as the ratio of Tax to Absorption.

Required Arguments

• state_table::AbstractRegionalTable: The regional data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol =:tax_rate`: The name of the parameter column.
• minimal::Bool = false: Whether to return a minimal output. If true, only the essential columns are returned: [:col, :region, :year, :parameter, output].

total_supply(data::AbstractRegionalTable; column::Symbol = :value, output::Symbol = :value)

Calculate the total supply for each commodity. The total supply is defined as the sum of:

• Intermediate_Supply
• Household_Supply

zero_profit(X::AbstractRegionalTable; column = :value, output = :value)

Calculate the zero profit condition. For each sector, the zero profit condition is defined as the sum of the following parameters:

• Intermediate_Demand
• Intermediate_Supply
• Value_Added

Required Arguments

• data::AbstractRegionalTable: The national data.

Keyword Arguments

• column::Symbol = :value: The column to be used for the calculation.
• output::Symbol = :value: The name of the output column.
• parameter::Symbol =:zero_profit`: The name of the parameter column.
• minimal::Bool = true: Whether to return a minimal output. If true, only the essential columns are returned: [:row, :year, :parameter, output].

Output

Returns a DataFrame with columns [:row, :col, :year, :parameter, output], where output is the renamed column column. Note that :col is filled with :zp and :parameter is filled with parameter.