From 40a35537d49f154c4802e614596874df3ac215a1 Mon Sep 17 00:00:00 2001 From: Wesley Ingwersen Date: Fri, 29 Jul 2022 11:48:25 -0400 Subject: [PATCH 1/6] rewrite and restructure README --- README.md | 57 ++++++++++++++++++++++++------------------------------- 1 file changed, 25 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 61a84830..8d503051 100644 --- a/README.md +++ b/README.md @@ -2,56 +2,49 @@ [![R CI/CD test](https://github.com/USEPA/stateior/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/USEPA/stateior/actions/workflows/R-CMD-check.yaml) -`stateior` is an R package for building multi-regional input-output (MRIO) models in the United States in support of creating [USEEIO models](https://www.epa.gov/land-research/us-environmentally-extended-input-output-useeio-models) in the [`useeior`](https://github.com/USEPA/useeior) package for US states and other purposes. +`stateior` is an R package for building multi-regional economic input-output (MRIO) tables of states in the United States, refered to as **StateIO** models. +Currently, `stateior` is capable of building two-region MRIO models at the [BEA](https://www.bea.gov/) Summary level of resolution in the US for all years from 2012-2017. +The two regions are State of Interest (SoI) and Rest of the US (RoUS). +`stateior` was initially conceived in support of creating state-specific versions of [USEEIO models](https://www.epa.gov/land-research/us-environmentally-extended-input-output-useeio-models), but may be used for other purposes where state input-output tables are used. +The package is intended to add transparency and reproducibility to the complex process of generating subnational input-output tables, which are not compiled by any statistical agency. -`stateior` describes a robust StateIO modeling framework and offers various functions for building, validating, visualizing, and writing out StateIO models. -`stateior` is in a stable development state. -Users intending to use the package for production purposes and applications should use [Releases](https://github.com/USEPA/stateior/releases). +`stateior` implements a robust commodity-industry modeling framework that models supply, use and trade of commodities by industries and final users in 50 U.S. states plus the District of Columbia and includes international import and export. +`stateior` offers various functions for building, validating, visualizing, writing, and loading StateIO models. +`stateior` is in a beta development state while the complete methodology and StateIO data products are under external peer-review. -See the following sections for installation and basic usage of `stateior`. +See the [Wiki](https://github.com/USEPA/stateior/wiki) for advanced uses, details about modeling approach, data and metadata, and how to contribute to `stateior`. -See [Wiki](https://github.com/USEPA/stateior/wiki) for advanced uses, details about modeling approach, data and metadata, and how to contribute to `stateior`. +## Usage -## Installation +There are two primary ways to use `stateior`. +1. To access the final data products in an R environment. This usage is the most simple and rapid and all that is required where the intention is only to review and use the two-region Make and Use tables. +2. To study, run, modify the source code for any or all of the model building steps, from raw data acquisition to final two-region table assembly. This is a developer use. -```r -# Install development version from GitHub -install.packages("devtools") -devtools::install_github("USEPA/stateior") -``` +### Use for Accessing Final Data Products (usage type #1) + +Install the most recent release version of `stateior` and attach it to the current R session. See [Releases](https://github.com/USEPA/stateior/releases) for all previously released versions. Note these steps will automatically install other R packages required by `devtools` and `stateior`. ```r -# Install a previously released version (e.g. v0.1.0) from GitHub +install.packages("devtools") devtools::install_github("USEPA/stateior@v0.1.0") +library(stateior) ``` -See [Releases](https://github.com/USEPA/stateior/releases) for all previously realeased versions. - -## Usage - -Currently, `stateior` is capable of building two-region MRIO models at the [BEA](https://www.bea.gov/) Summary level of resolution in the US. -The two regions are State of Interest (SoI) and Rest of the US (RoUS). - -Load two-region MRIO model results +Load desired StateIO data. See [Two Region Data](format_specs/TwoRegionData.md#data) for names and details of two-region MRIO data sets that are currently available. ```r -library(stateior) +#Load the two region domestic Use tables for 2012 for all states. This will download the data product from a remote server and load it into your R session as an R list . +TwoRegionDomesticUse_2012 <- loadStateIODataFile("TwoRegion_Summary_DomesticUse_2012") -# Load the latest version by default -data <- loadStateIODataFile(dataname) -# Example -TwoRegionDomesticUse_GA_RoUS <- loadStateIODataFile("TwoRegion_Summary_DomesticUse_2012")[["Georgia"]] +#Select the two region Use table for Georgia and Rest of the US. This will put this table into a standard R data frame named 'GA_TwoRegionDomesticUse_2012'. +GA_TwoRegionDomesticUse_2012 <- TwoRegionDomesticUse_2012[["Georgia"]] -# Specify version_number if a particular version is desired -data <- loadStateIODataFile(dataname, ver = version_number) -# Example -TwoRegionDomesticUse_GA_RoUS <- loadStateIODataFile("TwoRegion_Summary_DomesticUse_2012", ver = "0.1.0")[["Georgia"]] ``` +### Use for Developers (usage type #2) -See [Two Region Data](format_specs/TwoRegionData.md#data) for names and details of two-region MRIO data sets that are currently available. +For studying, replicating or modify the code, users will want to clone or copy the source code and review the code in R. See more in [Instructions for Developers](https://github.com/USEPA/stateior/wiki/Instructions-for-developers). ## Disclaimer The United States Environmental Protection Agency (EPA) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. EPA has relinquished control of the information and no longer has responsibility to protect the integrity , confidentiality, or availability of the information. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by EPA. The EPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by EPA or the United States Government. - From 4b3cd84c37cb96bc516975857a1abefd02a46bc6 Mon Sep 17 00:00:00 2001 From: Mo Li Date: Fri, 29 Jul 2022 14:47:21 -0700 Subject: [PATCH 2/6] Create StateData.md --- format_specs/StateData.md | 48 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 format_specs/StateData.md diff --git a/format_specs/StateData.md b/format_specs/StateData.md new file mode 100644 index 00000000..36d6e630 --- /dev/null +++ b/format_specs/StateData.md @@ -0,0 +1,48 @@ +# State IO Data Formats + +State IO data created by `stateior` are saved as `.rds` files and have the following components. Their formats are described below in each section. + +## Data + +| Item | Data Name1 | Data Structure | Description | +| ------------------------------ | ---------------------- | -------------- | ----------- | +| Make | State_Summary_Make_`year`_`version` | matrix | [The state Make](#State-Make) | +| Use | State_Summary_Use_`year`_`version` | matrix | [The state Use](#State-Use) | +| Domestic Use | State_Summary_DomesticUse_`year`_`version` | matrix | [The state Domestic Use](#State-Domestic-Use) | +| Commodity Output | State_Summary_CommodityOutput_`year`_`version` | numeric vector | [State total output by commodity](#State-Output-Vectors) | +| Industry Output | State_Summary_IndustryOutput_`year`_`version` | numeric vector | [State total output by industry](#State-Output-Vectors) | + +1 Data names on [Data Commons](https://edap-ord-data-commons.s3.amazonaws.com/index.html?prefix=stateio/). `year` and `version` are subject to change. + +### State Make +The state Make matrix is an `industry x commodity` matrix with amounts in commodities (in model year USD) being made by industries. +``` + commodities + +-------+ + industries | | + | Make | + +-------+ +``` + +### State Use +The state Use is a `commodity x industry` matrix with total amounts (in model year USD) of commodities being used by industries for intermediate production, or being used by final consumers. +State Use also includes commodity imports, exports and change in inventories as components of final demand, and value added components as inputs to industries. +The last column in Use is the international trade adjustment (ITA) vector containing value of all transportation and insurance services to import and customs duties in model year USD. +``` + industries, final demand, ITA + +---------------------------+ +commodities, | | +value added | Use | + +---------------------------+ +``` +The related `U_d` matrix provides commodity and value added use totals by industries and final demand that are only from the US. + +### State output vectors + +The state commodity output vector `q` and industry output vector `x` contain economic output in model year USD. + +``` +commodities +----q----+ + +industries +----x----+ +``` From 5e873c44c7b6b2e711b56aa17f61803540dea8c6 Mon Sep 17 00:00:00 2001 From: Mo Li Date: Fri, 29 Jul 2022 14:58:52 -0700 Subject: [PATCH 3/6] Add state IO description and usage in README --- README.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 8d503051..e0cc345a 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![R CI/CD test](https://github.com/USEPA/stateior/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/USEPA/stateior/actions/workflows/R-CMD-check.yaml) `stateior` is an R package for building multi-regional economic input-output (MRIO) tables of states in the United States, refered to as **StateIO** models. -Currently, `stateior` is capable of building two-region MRIO models at the [BEA](https://www.bea.gov/) Summary level of resolution in the US for all years from 2012-2017. +Currently, `stateior` is capable of creating IO tables for each US state and building two-region MRIO models based on those state IO tables at the [BEA](https://www.bea.gov/) Summary level of resolution in the US for all years from 2012-2017. The two regions are State of Interest (SoI) and Rest of the US (RoUS). `stateior` was initially conceived in support of creating state-specific versions of [USEEIO models](https://www.epa.gov/land-research/us-environmentally-extended-input-output-useeio-models), but may be used for other purposes where state input-output tables are used. The package is intended to add transparency and reproducibility to the complex process of generating subnational input-output tables, which are not compiled by any statistical agency. @@ -30,15 +30,30 @@ devtools::install_github("USEPA/stateior@v0.1.0") library(stateior) ``` -Load desired StateIO data. See [Two Region Data](format_specs/TwoRegionData.md#data) for names and details of two-region MRIO data sets that are currently available. +Load desired StateIO data. See [State Data](format_specs/TwoRegionData.md#data) and [Two Region Data](format_specs/TwoRegionData.md#data) for names and details of state and two-region MRIO data sets that are currently available, respectively. ```r -#Load the two region domestic Use tables for 2012 for all states. This will download the data product from a remote server and load it into your R session as an R list . +############## +# State Data # +############## +# Load the state domestic Use tables for 2012 for all states. +# This will download the data product from a remote server and load it into your R session as an R list. +StateDomesticUse_2012 <- loadStateIODataFile("State_Summary_DomesticUse_2012") + +# Select the Georgia Use table. +# This will put this table into a standard R data frame named 'GA_DomesticUse_2012'. +GA_DomesticUse_2012 <- StateDomesticUse_2012[["Georgia"]] + +################### +# Two-Region Data # +################### +# Load the two region domestic Use tables for 2012 for all states. +# This will download the data product from a remote server and load it into your R session as an R list. TwoRegionDomesticUse_2012 <- loadStateIODataFile("TwoRegion_Summary_DomesticUse_2012") -#Select the two region Use table for Georgia and Rest of the US. This will put this table into a standard R data frame named 'GA_TwoRegionDomesticUse_2012'. +# Select the two region Use table for Georgia and Rest of the US. +# This will put this table into a standard R data frame named 'GA_TwoRegionDomesticUse_2012'. GA_TwoRegionDomesticUse_2012 <- TwoRegionDomesticUse_2012[["Georgia"]] - ``` ### Use for Developers (usage type #2) From ee412b1cefcfc7e38dec01aa03ad330230c64ef5 Mon Sep 17 00:00:00 2001 From: Wesley Ingwersen Date: Mon, 1 Aug 2022 11:31:04 -0400 Subject: [PATCH 4/6] change StateData to OneRegionData and use useeior format specs --- format_specs/OneRegionData.md | 18 +++++++++++++ format_specs/StateData.md | 48 ----------------------------------- 2 files changed, 18 insertions(+), 48 deletions(-) create mode 100644 format_specs/OneRegionData.md delete mode 100644 format_specs/StateData.md diff --git a/format_specs/OneRegionData.md b/format_specs/OneRegionData.md new file mode 100644 index 00000000..ff6d75a8 --- /dev/null +++ b/format_specs/OneRegionData.md @@ -0,0 +1,18 @@ +# One Region IO Data Formats + +One region IO data created by `stateior` are data for single states saved as `.rds` files and have the following components. The tables use the same formats for the matrices with the same names in [useeior v1.1.0](https://github.com/USEPA/useeior/tree/v1.1.0). + +## Data + +| Item | Data Name1 | Data Structure | Description | +| ------------------------------ | ---------------------- | -------------- | ----------- | +| Make | State_Summary_Make_`year`_`version` | matrix | [Make (V)](https://github.com/USEPA/useeior/blob/v1.1.0/format_specs/Model.md#v) | +| Use | State_Summary_Use_`year`_`version` | matrix | [Use (U)](https://github.com/USEPA/useeior/blob/v1.1.0/format_specs/Model.md#u) 2 | +| Domestic Use | State_Summary_DomesticUse_`year`_`version` | matrix | [Domestic Use (U_d)](https://github.com/USEPA/useeior/blob/v1.1.0/format_specs/Model.md#u) 2 | +| Commodity Output | State_Summary_CommodityOutput_`year`_`version` | numeric vector | [Output Vectors](https://github.com/USEPA/useeior/blob/v1.1.0/format_specs/Model.md#output-vectors) | +| Industry Output | State_Summary_IndustryOutput_`year`_`version` | numeric vector | [Output Vectors](https://github.com/USEPA/useeior/blob/v1.1.0/format_specs/Model.md#output-vectors)| + +1 Data names on [Data Commons](https://edap-ord-data-commons.s3.amazonaws.com/index.html?prefix=stateio/). `year` and `version` are subject to change. + +2 These Use tables add, as the final column, the international trade adjustment (ITA) containing the value of all transportation and insurance services and customs duties + diff --git a/format_specs/StateData.md b/format_specs/StateData.md deleted file mode 100644 index 36d6e630..00000000 --- a/format_specs/StateData.md +++ /dev/null @@ -1,48 +0,0 @@ -# State IO Data Formats - -State IO data created by `stateior` are saved as `.rds` files and have the following components. Their formats are described below in each section. - -## Data - -| Item | Data Name1 | Data Structure | Description | -| ------------------------------ | ---------------------- | -------------- | ----------- | -| Make | State_Summary_Make_`year`_`version` | matrix | [The state Make](#State-Make) | -| Use | State_Summary_Use_`year`_`version` | matrix | [The state Use](#State-Use) | -| Domestic Use | State_Summary_DomesticUse_`year`_`version` | matrix | [The state Domestic Use](#State-Domestic-Use) | -| Commodity Output | State_Summary_CommodityOutput_`year`_`version` | numeric vector | [State total output by commodity](#State-Output-Vectors) | -| Industry Output | State_Summary_IndustryOutput_`year`_`version` | numeric vector | [State total output by industry](#State-Output-Vectors) | - -1 Data names on [Data Commons](https://edap-ord-data-commons.s3.amazonaws.com/index.html?prefix=stateio/). `year` and `version` are subject to change. - -### State Make -The state Make matrix is an `industry x commodity` matrix with amounts in commodities (in model year USD) being made by industries. -``` - commodities - +-------+ - industries | | - | Make | - +-------+ -``` - -### State Use -The state Use is a `commodity x industry` matrix with total amounts (in model year USD) of commodities being used by industries for intermediate production, or being used by final consumers. -State Use also includes commodity imports, exports and change in inventories as components of final demand, and value added components as inputs to industries. -The last column in Use is the international trade adjustment (ITA) vector containing value of all transportation and insurance services to import and customs duties in model year USD. -``` - industries, final demand, ITA - +---------------------------+ -commodities, | | -value added | Use | - +---------------------------+ -``` -The related `U_d` matrix provides commodity and value added use totals by industries and final demand that are only from the US. - -### State output vectors - -The state commodity output vector `q` and industry output vector `x` contain economic output in model year USD. - -``` -commodities +----q----+ - -industries +----x----+ -``` From 58425ca36718c9f9e080a18502eaef9021ee6c83 Mon Sep 17 00:00:00 2001 From: Wesley Ingwersen Date: Mon, 1 Aug 2022 11:33:21 -0400 Subject: [PATCH 5/6] update state data link to one-region data --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e0cc345a..7dc0cd79 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ devtools::install_github("USEPA/stateior@v0.1.0") library(stateior) ``` -Load desired StateIO data. See [State Data](format_specs/TwoRegionData.md#data) and [Two Region Data](format_specs/TwoRegionData.md#data) for names and details of state and two-region MRIO data sets that are currently available, respectively. +Load desired StateIO data. See [One Region Data](format_specs/OneRegionData.md#data) and [Two Region Data](format_specs/TwoRegionData.md#data) for names and details of one- and two-region MRIO data sets that are currently available, respectively. ```r ############## From 172a3b71b1c5db6b3351b74eb670987bf512c711 Mon Sep 17 00:00:00 2001 From: Wesley Ingwersen Date: Mon, 1 Aug 2022 11:37:16 -0400 Subject: [PATCH 6/6] further update change from StateData to OneRegion data --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7dc0cd79..e97bacc0 100644 --- a/README.md +++ b/README.md @@ -34,15 +34,15 @@ Load desired StateIO data. See [One Region Data](format_specs/OneRegionData.md#d ```r ############## -# State Data # +# One-Region Data # ############## -# Load the state domestic Use tables for 2012 for all states. +# Load the state one-region (state only) domestic Use tables for 2012 for all states. # This will download the data product from a remote server and load it into your R session as an R list. -StateDomesticUse_2012 <- loadStateIODataFile("State_Summary_DomesticUse_2012") +OneRegionDomesticUse_2012 <- loadStateIODataFile("State_Summary_DomesticUse_2012") # Select the Georgia Use table. # This will put this table into a standard R data frame named 'GA_DomesticUse_2012'. -GA_DomesticUse_2012 <- StateDomesticUse_2012[["Georgia"]] +GA_DomesticUse_2012 <- OneRegionDomesticUse_2012[["Georgia"]] ################### # Two-Region Data #