-
Notifications
You must be signed in to change notification settings - Fork 5
/
vignette_readgcam.Rmd
117 lines (83 loc) · 5.37 KB
/
vignette_readgcam.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
---
title: "User Guide"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{User Guide}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
resource_files:
- vignetteFigs
---
<!-------------------------->
<!-------------------------->
# Introduction
<!-------------------------->
<!-------------------------->
<p align="center"> <img src="vignetteFigs/divider.png" width="1400"></p>
`gcamextractor` is a package to extract GCAM data into standardized data tables which can be used downstream in other models. `gcamextractor` uses `rgcam` to connect to GCAM databases and then processes the data into more commonly used units as well as re-organizes the data into tables with common column names. This allows all the data to be saved in combined tables. Additionally, `gcamextractor` aggregates data by parameter, class 1 and class 2. This allows users to quickly plot and analyze data at different degrees of detail.
`gcamextractor::readgcam` will return a list as csv files as well directly as a list of R tables containing:
* data: a dataframe with the original data
* dataAggParam: a dataframe with the data aggregated to the parameter
* dataAggClass1: a dataframe with the data aggregated to class 1
* dataAggclass2: a dataframe with the data aggregated to class 2
* dataAll: a dataframe with the original data as well as original queries and values before any conversions
* scenarios: A list of the scenarios
* queries: A list of the queries used to extract the data
The figure below shows the workflow of how `gcamextractor` connects to a GCAM database and its outputs.
<br>
<p align="center"> <img src="vignetteFigs/gcamextractor_workflow.jpg" width="1400"></p>
<!-------------------------->
<!-------------------------->
# Read GCAM database
<!-------------------------->
<!-------------------------->
<p align="center"> <img src="vignetteFigs/divider.png" width="1400"></p>
```{r, eval=F}
library(gcamextractor)
path_to_gcam_database <- "E:/gcamfolder/output/database_ref" # Change the path based on your GCAM database location
gcamextractor::params # view available parameters
dataGCAM <- gcamextractor::readgcam(gcamdatabase = path_to_gcam_database,
regionsSelect = c("Colombia"), # Set to "All" to read in all available regions
paramsSelect = "pop",
folder = "my_output_folder") # Set to "All" to read in all available params
# View your data
df <- dataGCAM$data; df
dfParam <- dataGCAM$dataAggParam; dfParam
dfClass1 <- dataGCAM$dataAggClass1; dfClass1
dfClass2 <- dataGCAM$dataAggClass1; dfClass2
```
<!-------------------------->
<!-------------------------->
# Read GCAM .Proj file
<!-------------------------->
<!-------------------------->
<p align="center"> <img src="vignetteFigs/divider.png" width="1400"></p>
Initial extraction of GCAM data can take a while and so `gcamextractor` also includes the option to save the raw extracted outputs as `.Proj` files which can be shared and read in as well. A default example `.Proj` file `gcamextractor::exmapleGCAMproj` is included with the package. The following script shows how this can be read into `gcamextractor`.
```{r, eval=F}
library(gcamextractor)
dataGCAM <- gcamextractor::readgcam(dataProjFile = gcamextractor::example_gcamv54_argentina_colombia_2025_proj, # Or provide path to .proj file
folder = "my_output_folder")
```
<!-------------------------->
<!-------------------------->
# Output Structure
<!-------------------------->
<!-------------------------->
<p align="center"> <img src="vignetteFigs/divider.png" width="1400"></p>
The following figure shows the column headers of the `dataAll` outputs from gcamextractor. Other tables have a subset of these columns, such as in the case of `data` which only keeps relevant columns and drops columns such as `origScen` and `origQuery` which refer to the original data in GCAM. Other tables such as `dataAggClass1` removes the `class 2` columns and then aggregates the data over `class 1` variables.
<p align="center"> <img src="vignetteFigs/example_structure.png" width="1400"></p>
<!-------------------------->
<!-------------------------->
# Available Paramaters
<!-------------------------->
<!-------------------------->
<p align="center"> <img src="vignetteFigs/divider.png" width="1400"></p>
Users can get a list of all available params and queries as shown below. The [parameters](https://jgcri.github.io/gcamextractor/articles/vignette_parameters.html) page lists details on each parameter, how it was calculated and cites any sources when available. `gcamextractor::map_param_query` gives a list of all parameters and the corresponding queries used to extract that data from GCAM. Additionally, `gcamextractor::map_param_query` also groups the various parameters into higher level groups which can then be called in the `paramSelect` argument of `gcamextractor` to extractor all the params in those groups. The groups also include curated parameters for particular models such as `CERF` and `GO`.
```{r, eval=F}
library(gcamextractor)
gcamextractor::params # Get all params
gcamextractor::queries # Get all queries used
gcamextractor::map_param_query # Get a table of params and the relevants queries used to extract and calculate them.
```
<!-- Add params list figure -->
<p align="center"> <img src="vignetteFigs/ParamList.png" width="1200"></p>