Skip to content

Commit

Permalink
Merge pull request #17 from USEPA/dev
Browse files Browse the repository at this point in the history 
Improve README and documentation for release
  • Loading branch information
@MoLi7
MoLi7 authored Aug 1, 2022
2 parents ecbeda9 + 172a3b7 commit 6fbb08a
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 34 deletions.
76 changes: 42 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,64 @@
<!-- badges: start -->
[![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 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.

`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 [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
library(stateior)

# Load the latest version by default
data <- loadStateIODataFile(dataname)
# Example
TwoRegionDomesticUse_GA_RoUS <- loadStateIODataFile("TwoRegion_Summary_DomesticUse_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"]]
##############
# One-Region Data #
##############
# 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.
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 <- OneRegionDomesticUse_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'.
GA_TwoRegionDomesticUse_2012 <- TwoRegionDomesticUse_2012[["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.


18 changes: 18 additions & 0 deletions format_specs/OneRegionData.md
View file
Original file line number Diff line number Diff line change
@@ -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 Name<sup>1</sup> | 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) <sup>2</sup> |
| 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) <sup>2</sup> |
| 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)|

<sup>1</sup> Data names on [Data Commons](https://edap-ord-data-commons.s3.amazonaws.com/index.html?prefix=stateio/). `year` and `version` are subject to change.

<sup>2</sup> 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

0 comments on commit 6fbb08a

Please sign in to comment.