In ebimodeling/ghgvcR: Greenhouse Gas Value Calculator

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

---

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. 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

#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.

#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, the ruby app we've built that takes advantage of the Rserve functionality. A working version is available at http://www.ecosystemservicescalc.org/.

ghgvcr can be run as a docker container, or set up by running 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.

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

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

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)

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

ebimodeling/ghgvcR documentation built on April 28, 2021, 8:19 p.m.