-
Notifications
You must be signed in to change notification settings - Fork 6
/
README.Rmd
155 lines (91 loc) · 6.23 KB
/
README.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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
ghgvcr
======
R implementation of the Greenhouse Gas Value Calculator
Citation: Kristina J. Teixeira and Evan H. Delucia 2011. The greenhouse gas value of ecosystems. Global Change Biology. 17(1):425–438 doi: 10.1111/j.1365-2486.2010.02220.x
[](https://travis-ci.org/ebimodeling/ghgvcR)
-------
**ghgvcR** serves two main functions:
1. Provide an `R` package to allow calculation of climate regulating values from within R by submitting an XML or JSON file of inputs.
2. Provide a web service capable of accepting web requests in XML or JSON format and providing climate regulating value results and figures.
### Installation
If you like rstudio and `devtools`, simply `devtools::install_github("ebimodeling/ghgvcr")` will handle installation. Alternatively, clone this repository, then in a terminal at the root of the repository type `R CMD INSTALL .`.
### USE CASE 1: ghgvcR as an R package for CRV calculation
`ghgvcr` provides two main functions: `calc_ghgv()` and `get_biome()`.
`get_biome()` takes a lat/lng pair and returns a list of likely ecosystems at that location, as well as parameters that determine the CRV calculation for each. The ecosystems can be easily used to create a list of locations and ecosystems to submit as an input to `calc_ghgv()`, which will return a JSON string of CRV values and can optionally write results to a CSV file and save plot images.
`get_biome()` requires a significant number of files to run. Those files are avialable as a zip file from [here](TODO: paste link). Unzipped they require nearly 10GB of disk space. By default this data is assumed to reside inside `/app/data`, but the directory can be changed by specifying `data_dir` as a parameter passed to `get_biome()`. See the function documentation for more information on available parameters.
#### A Simple Example
``` {r}
#get all ecosystems likely at latitude -15.62, longitude -50.69 and save them in a file named 'biome.csv'
#returns a list of biomes in JSON format
biomes_json <- get_biome(-15.62, -50.69, data_dir = '/data/ghgvcD/', output_filename = 'biome.csv', save_output = TRUE)
#convert the biomes_json string to an R list
biomes_list <- jsonlite::fromJSON(biomes_json)
```
The next step is to compose a list to send to `calc_ghgv()`. We can use the file at `inst/config/single_site.json` as a framework to construct our list of ecosystems.
``` {r}
#double fromJSON needed because of how R writes JSON objects to files.
example_inputs <- fromJSON(fromJSON('inst/config/single_site.json'))
#create the initial input list with default global options
our_intputs <- list('options' = example_inputs$options, sites = list())
# Add the Grass biome from our above selection.
our_inputs$sites$site_1_data$Grass <- biomes_list$Grass
# run the calculator, save the output data, and save a plot with "Equivalent miles driven in an average-sized car" as units.
res <- calc_ghgv(our_inputs, save_output = TRUE, save_plots = TRUE, plot_units = "mi")
```
### USE CASE 2: ghgvcr as a web service
Best if you'd like to allow for repeated scripted calls to a web server that contains `ghgvcr`, or run a web app that makes 'api' calls to the `ghgvcr` library. In this case, we suggest [ghgvc](https://github.com/rubyforgood/ghgvc), the ruby app we've built that takes advantage of the Rserve functionality. A working version is available at [http://www.ecosystemservicescalc.org/](http://www.ecosystemservicescalc.org/).
ghgvcr can be run as a docker container, or set up by running [Rserve](https://www.rforge.net/Rserve/). To run it as a docker container, first install the zipped map data in `ghgvcD` as a sibling to `ghgvcr`. You'll need `docker` and `docker-compose` installed. Then from the ghgvcr repository, run
> docker-compose build
> docker-compose up
This will start a docker daemon. `ghgvcr` can be communicated with by making Rserve calls to port 6311 from any language that supports Rserve.
Alternatively, Rserve can be started from R and run as a daemon itself without the use of docker.
### Installing the ghgvcr package on the PEcAn 1.2.6 VM
The below information is outdated, though the functionality is similar.
------
The bash and R code snippets below install dependencies, and only need to be run once.
```sh
sudo apt-get install git
sudo apt-get install libcurl4-openssl-dev # dependency of Rcurl,
git clone https://github.com/dlebauer/pecan.git pecan
git clone https://github.com/dlebauer/ghgvcR.git ghgvcR
R
```
```{r include = TRUE, message = FALSE}
library(ghgvcr)
library(XML)
library(jsonlite)
options(warn=FALSE)
```
### Example of how to run the calculator
* This can be run at the command line: `./src/ghgvc_script.R`
```{r results='hide', comment=NA, warning=FALSE}
config_file <- system.file("config/config.xml", package = "ghgvcr")
config <- xmlToList(xmlParse(config_file, validate=F))
#Calculator
ghgvc_output <- ghgvc(config, , make_plots = FALSE, write_data = FALSE)
ghgvc_output.json <- toJSON(ghgvc_output)
```
```{r results='hide', comment=NA, warning=FALSE}
multisite_config.xml <- system.file("config/multisite_config.xml", package = "ghgvcr")
multipft_config.list <- xmlToList(xmlParse(multisite_config.xml))
x2 <- ghgvc(multipft_config.list, make_plots = FALSE, write_data = FALSE)
writeLines(x2, "inst/extdata/multipft_output.json")
write.csv(as.data.frame(fromJSON(x2)), "inst/extdata/multipft_output.csv")
```
# Docker
## Using Docker Compose
After cloning this repo, use docker-compose during development and testing.
The first time you run the container, use the `download-netcdf.sh` script
to download the required netcdf files.
> docker-compose run --rm ghgvcr ./download-netcdf.sh
For testing and development, you can drop into an interactive bash shell.
> docker-compose run --rm ghgvcr bash # drop into a bash shell
You can also run one-off shell commands.
> docker-compose run --rm ghgvcr Rscript -e "devtools::check()"
## Building a Docker image
Build & push should occur automatically via travis, but you may want to
build and/or push an image directly up to docker hub.
To build the image, use the `docker build` command.
> docker build -t ebimodeling/ghgvcr .
To push to Docker Hub, after logging in, use `docker push`
> docker push ebimodeling/ghgvcr