Misc updates

adding a schematic
update readme
update checks

Author: realxinzhao

README.md

@@ -1,4 +1,5 @@
 <!-- badges: start -->
+[![pages-build-deployment](https://github.com/JGCRI/gcamfaostat/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/JGCRI/gcamfaostat/actions/workflows/pages/pages-build-deployment)
 [![build](https://github.com/JGCRI/gcamfaostat/workflows/build/badge.svg)](https://github.com/JGCRI/gcamfaostat/workflows/build/badge.svg?branch=main)
 [![test_coverage](https://github.com/JGCRI/gcamfaostat/actions/workflows/test_coverage.yml/badge.svg?branch=main)](https://github.com/JGCRI/gcamfaostat/actions/workflows/test_coverage.yml)
 [![docs](https://github.com/JGCRI/gcamfaostat/actions/workflows/docs.yaml/badge.svg?branch=main)](https://github.com/JGCRI/gcamfaostat/actions/workflows/docs.yaml)
@@ -24,7 +25,7 @@ The package is documented in the [online manual](https://jgcri.github.io/gcamfao
 
 ***
 
-### Quick Start
+### Quick Start in R (> 4.0) & Rstudio
 
 #### 1. Download and install:
 
@@ -54,7 +55,7 @@ The package is documented in the [online manual](https://jgcri.github.io/gcamfao
 ### Package structure
 
 
-* `gcamfaostat` processes [input data](https://jgcri.github.io/gcamfaostat/articles/vignette_preparing_data.html#metadata) to output data in a format that is needed for downstream processing and modeling, e.g., [data used in gcamdata-aglu-FAO](https://github.com/JGCRI/gcam-core/tree/master/input/gcamdata/inst/extdata/aglu/FAO) (see the schmatic below).
+* `gcamfaostat` processes [input data](https://jgcri.github.io/gcamfaostat/articles/vignette_preparing_data.html#metadata) to output data in a format that is needed for downstream processing and modeling, e.g., [data used in gcamdata-aglu-FAO](https://github.com/JGCRI/gcam-core/tree/master/input/gcamdata/inst/extdata/aglu/FAO) (see the schematic below).
 * Input data was stored in the [Prebuilt Data](https://github.com/JGCRI/gcamfaostat/blob/main/data/PREBUILT_DATA.rda) of the package. The raw data is archived on Zenodo (see URL in the [`FF_download_RemoteArchive`](https://github.com/JGCRI/gcamfaostat/blob/main/R/xfaostat_helper_funcs.R#L144) function) to ensure the processing is 100% replicable. Users can also download the latest data using [`FF_download_FAOSTAT`](https://github.com/JGCRI/gcamfaostat/blob/main/R/xfaostat_helper_funcs.R#90). 
 * All intermediate processing and data flows are transparent and traceable. See [Processing Flow](https://jgcri.github.io/gcamfaostat/articles/vignette_processing_flow.html) for data-tracing examples. 
 

man/figures/Fig_FAOSTAT_gcamdata.jpg

@@ -140,6 +140,16 @@ @article{Zhao2021Estimating
 	month=7,
 	day=20,
 }
+@article{Zhao2020critical,
+  title={The critical role of conversion cost and comparative advantage in modeling agricultural land use change},
+  author={Zhao, Xin and Calvin, Katherine V and Wise, Marshall A},
+  journal={Climate Change Economics},
+  volume={11},
+  number={01},
+  pages={2050004},
+  year={2020},
+  publisher={World Scientific}
+}
 @article{Bruckner2019FABIO,
 	journal={Environmental Science & Technology},
 	doi={10.1021/acs.est.9b03554},
@@ -190,6 +200,15 @@ @article{Chepeliev2022JGEA
 	month=6,
 	day=25,
 }
+@article{zhao2021role,
+  title={The role of global agricultural market integration in multiregional economic modeling: Using hindcast experiments to validate an Armington model},
+  author={Zhao, Xin and Calvin, Katherine V and Wise, Marshall A and Iyer, Gokul},
+  journal={Economic Analysis and Policy},
+  volume={72},
+  pages={1--17},
+  year={2021},
+  publisher={Elsevier}
+}
 @article{Lampe2014AgMIP,
 	journal={Agricultural Economics},
 	doi={10.1111/agec.12086},
@@ -275,6 +294,15 @@ @article{calvin2019gcam
   publisher={Lawrence Berkeley National Lab.(LBNL), Berkeley, CA (United States); Pacific~…},
   DOI={10.5194/gmd-12-677-2019}
 }
+@article{bond2019gcamdata,
+  title={gcamdata: An R package for preparation, synthesis, and tracking of input data for the GCAM integrated human-earth systems model},
+  author={Bond-Lamberty, Ben and Dorheim, Kalyn and Cui, Ryna and Horowitz, Russell and Snyder, Abigail and Calvin, Katherine and Feng, Leyang and Hoesly, Rachel and Horing, Jill and Kyle, G Page and others},
+  journal={Journal of Open Research Software},
+  volume={7},
+  number={1},
+  year={2019},
+  publisher={Ubiquity Press}
+}
 @article{divittorio2020moirai,
   title={Moirai Version 3: A Data Processing System to Generate Recent Historical Land Inputs for Global Modeling Applications at Various Scales},
   author={Di Vittorio, Alan and Vernon, Christopher R and Shu, Shijie},

man/figures/Fig_data_processing_flow.jpg

@@ -17,18 +17,26 @@ knitr::opts_chunk$set(
 ```
 
 
-# 
+## Introduction
 
+Global economic and multisector dynamic models have become pivotal tools for investigating complex interactions between human activities and the environment, as evident in recent research [@Doelman2022Quantifying;@Fujimori2022Land-based;@IPCC2022Annex;@Ven2023multimodel]. Agriculture and land use (AgLU) plays a critical role in these models, particularly when used to address key agroeconomics questions [@Graham2023Agricultural;@Yarlagadda2023Trade;@Zhang2023Agriculture;@Zhao2021Global;@Zhao2020critical]. Sound economic modeling hinges significantly upon the accessibility and quality of data [@Bruckner2019FABIO;@Calvin2022GMD;@Chepeliev2022JGEA]. The Food and Agriculture Organization Statistical Database (FAOSTAT) [@FAOSTAT2023FAOSTAT] serves as the most important data source, offering open-access data on country-level agricultural production, land use, trade, food consumption, nutrient content, prices, and more. However, the raw data from FAOSTAT requires cleaning, balancing, and synthesis, involving assumptions such as interpolation and mapping, which can introduce uncertainties. It is noteworthy that each agroeconomic modeling team typically develops its own assumptions and methods to prepare and process FAOSTAT data [@bond2019gcamdata]. While largely overlooked, the uncertainty in the base calibration data likely contributed to the disparities in model outcomes [@Lampe2014AgMIP;@zhao2021role]. Hence, our motivation is to create an open-source tool (`gcamfaostat`) for the preparation, processing, and synthesis of FAOSTAT data for global agroeconomic modeling.  The tool can also be valuable to a broader range of users interested in understanding global agriculture trends and dynamics, as it provides accessible and processed data and [visualization](https://jgcri.github.io/gcamfaostat/articles/vignette_visualization.html) functions.
 
-# gcamdata and gcamfaostat
-`gcamdata` [@bond_lamberty_2023]
+
+## gcamfaostat, gcamdata, GCAM, and the broader modeling community
+
+`gcamdata` [@bond_lamberty_2023] 
+
+Figure 1  shows the relationship between `gcamfaostat` and `gcamdata` with example modules of each packages presented.
+
+![Figure 1. Original framework of using FAOSTAT data in large-scale modeling](../man/figures/Fig_FAOSTAT_gcamdata.jpg){width=85%} 
 
 
 
 
 Figure 1  shows the relationship between `gcamfaostat` and `gcamdata` with example modules of each packages presented.
 
-![Figure 1. Relationship between gcamfaostat and gcamdata](../man/figures/Fig_gcamfaostat_and_gcamdata.jpg) 
+![Figure 2. New framework using `gcamfaostat` to process FAOSTAT data](../man/figures/Fig_gcamfaostat_and_gcamdata.jpg){width=95%} 
+
 **Figure 1. Relationship between `gcamfaostat` and `gcamdata`.** Modules with identifier `_xfaostat_` only exists in `gcamfaostat`. Agriculture and land use (AgLU) related modules (`_aglu_`) that rely on outputs from `gcamfaostat` can run in both packages. Other `gcamdata` modules processing data in areas such as energy, emissions, water, and socioeconomics only exist in `gcamdata`.