forked from ebimodeling/ghgvcR
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
157 lines (100 loc) · 6.74 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
156
157
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/jaydorsey/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 `/home/ghgvcr/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!
## Building a Docker image of the Calculator
```
> docker build --rm --force-rm \ # build a docker image, don't keep temp stuff
--tag ebimodeling/ghgvcr \ # tag the resulting image with owner and name
. # build the current directory
```
## Run the Calculator in a container
You can run the R calculator in a container this way or, when paired with the
`ghgvc` Rails application, via the docker-compose configuration defined in that
project.
```
> docker run -it --rm \ # run, attach to the container, destroy it when exit
--volume /path/to/the/data:/home/ghgvcr/data \ # mount the tons of data
--publish 6311:6311 \ # forward the container's port 6311 to localhost 6311
--name ghgvcr-serve \ # name the running container
ebimodeling/ghgvcr # the tag given during `docker build ...`
```
## Running R tests for local development
1. Remove `tests/` from `.dockerignore` if it is present
2. Run `docker build .` in the project's root directory
3. Get a shell into the container with `docker run -it <id from step 2> /bin/bash`
4. Inside the container, run `R CMD build .` to generate the tarball used by the checker
(note the trailing `.`)
5. Run `R CMD check ghgvcr_2.0.tar.gz --as-cran --no-manual --no-manual` This checks the
R code, and should report no errors.