25.9 The PEcAn Docker API

If you have a running instance of Dockerized PEcAn (or other setup where PEcAn workflows are submitted via RabbitMQ), you have the option of running and managing PEcAn workflows using the pecanapi package.

For more details, see the pecanapi package vignette and function-level documentation. What follows is a lightning introduction.

25.9.0.1 Installation

The package can be installed directly from GitHub via devtools::install_github:

devtools::install_github("pecanproject/pecan/api@develop")

25.9.0.2 Creating and submitting a workflow

With pecanapi, creating a workflow, submitting it to RabbitMQ, monitoring its progress, and processing its output can all be accomplished via an R script.

Start by loading the package (and the magrittr package, for the %>% pipe operator).

library(pecanapi)
library(magrittr)

Set your PEcAn database user ID, and create a database connection object, which will be used for database operations throughout the workflow.

options(pecanapi.user_id = 99000000002)
con <- DBI::dbConnect(
  drv = RPostgres::Postgres(),
  user = "bety",
  password = "bety",
  host = "localhost",
  port = 5432
)

Find model and site IDs for the site and model you want to run.

model_id <- get_model_id(con, "SIPNET", "136")
all_umbs <- search_sites(con, "umbs%disturbance")
site_id <- subset(all_umbs, !is.na(mat))[["id"]]

Insert a new workflow into the PEcAn database, and extract its ID.

workflow <- insert_new_workflow(con, site_id, model_id,
                                start_date = "2004-01-01",
                                end_date = "2004-12-31")
workflow_id <- workflow[["id"]]

Pull all of this information together into a settings list object.

settings <- list() %>%
  add_workflow(workflow) %>%
  add_database() %>%
  add_pft("temperate.deciduous") %>%
  add_rabbitmq(con = con) %>%
  modifyList(list(
    meta.analysis = list(iter = 3000, random.effects = list(on = FALSE, use_ghs = TRUE)),
    run = list(inputs = list(met = list(source = "CRUNCEP", output = "SIPNET", method = "ncss"))),
    ensemble = list(size = 1, variable = "NPP")
  ))

Submit the workflow via RabbitMQ, and monitor its progress in the R process.

submit_workflow(settings)
watch_workflow(workflow_id)

Use THREDDS to access and analyze the output.

sipnet_out <- ncdf4::nc_open(run_dap(workflow_id, "2004.nc"))
gpp <- ncdf4::ncvar_get(sipnet_out, "GPP")
time <- ncdf4::ncvar_get(sipnet_out, "time")
ncdf4::nc_close(sipnet_out)
plot(time, gpp, type = "l")