Overview
rpecanapi is an open source R package to interact with the PEcAn Project Server(s) & leverage the functionality of the PEcAn bioinformatics toolbox. The Predictive Ecosystem Analyser (PEcAn) Project is an open source framework initiated to meet the demands for more accessible, transparent & repeatable modeling of ecosystems. To know more about the PEcAn Project, check out the PEcAn Github Repository
This package allows users to get relevant information from the PEcAn database as well as submit PEcAn workflows.
Installation
You can install the development version of rpecanapi from GitHub as follows:
# install.packages("devtools")
devtools::install_github("PecanProject/rpecanapi")Usage
The following snippets assume that the PEcAn RESTful API Server is running on http://pecan.localhost:80. This can be replaced with any other appropriate PEcAn Server URL.
- Getting Started
- Get Information about PEcAn Models
- Get Information about PEcAn Sites
- Get Information about PEcAn PFTs (Plant Functional Types)
- Get Information about PEcAn Formats
- Get Information about PEcAn Inputs
- Get Information about PEcAn Workflows
- Submit a PEcAn Workflow for Execution
- Get Information about PEcAn Runs
- Plots & File Downloads for Workflows & Runs
Getting Started
Ping the PEcAn API Server
ping(server)
#> $request
#> [1] "ping"
#> $response
#> [1] "pong"Get General Information about the Server & PEcAn Version
get.status(server)
# $host_details
# $host_details$hostid
# [1] 99
# $host_details$hostname
# [1] ""
# $host_details$start
# [1] 9.9e+10
# $host_details$end
# [1] 1e+11
# $host_details$sync_url
# [1] ""
# $host_details$sync_contact
# [1] ""
# $host_details$authentication_required
# [1] "FALSE"
# $pecan_details
# $pecan_details$version
# [1] "develop"
# $pecan_details$branch
# [1] "develop"
# $pecan_details$gitsha1
# [1] "48a3b259fd03512c145b4d6eb387467e56ab49b4"Get Information about PEcAn Models
Search for PEcAn Model(s)
search.models(server, model_name='sip', revision='r')
#> $models
#> model_id model_name revision
#> 1 1000000014 SIPNET r136
#> 2 1000000022 SIPNET ssr
#> $count
#> [1] 2Get the details of a PEcAn Model
get.model(server, model_id='1000000014')
#> $modeltype_id
#> [1] 3
#> $model_type
#> [1] "SIPNET"
#> $model_id
#> [1] 1000000014
#> $model_name
#> [1] "SIPNET"
#> $revision
#> [1] "r136"
#> $inputs
#> input required
#> 1 met TRUE
#> 2 poolinitcond FALSEGet Information about PEcAn Sites
Search for PEcAn Site(s)
search.sites(server, sitename='willow')
#> $sites
#> id sitename
#> 1 676 Willow Creek (US-WCr)
#> 2 1108 Willow Creek (WC)-Chequamegon National Forest
#> 3 1202 Tully_willow
#> 4 1223 Saare SRF willow plantation
#> 5 1000005151 Willow Creek (US-WCr)
#> $count
#> [1] 5Get the details of a PEcAn Site
get.site(server, site_id='676')
#> $id
#> [1] 676
#> $city
#> [1] "Park Falls Ranger District"
#> $state
#> [1] "Wisconsin"
#> $country
#> [1] "US"
#> $mat
#> [1] 4
#> $map
#> [1] 815
#> $soil
#> [1] ""
#> $som
#> [1] "NA"
#> $notes
#> [1] "MF"
#> $soilnotes
#> [1] ""
#> $sitename
#> [1] "Willow Creek (US-WCr)"
#> $greenhouse
#> [1] FALSE
#> $sand_pct
#> [1] 42.52
#> $clay_pct
#> [1] 20.17
#> $time_zone
#> [1] "America/Chicago"Get Information about PEcAn PFTs (Plant Functional Types)
Search for PEcAn PFT(s)
search.pfts(server, pft_name='deciduous', model_type='sipnet')
#> $pfts
#> model_type pft_id pft_name pft_type
#> 1 SIPNET 41 temperate.deciduous plant
#> 2 SIPNET 1000000105 temperate.deciduous.IF plant
#> 3 SIPNET 1000000107 temperate.deciduous_SDA plant
#> 4 SIPNET 1000000115 temperate.deciduous.ALL plant
#> 5 SIPNET 1000000118 temperate.deciduous.ALL.NORMAL plant
#> 6 SIPNET 2000000017 tundra.deciduous.NGEE_Arctic plant
#> 7 SIPNET 2000000045 temperate.broadleaf.deciduous plant
#> $count
#> [1] 7Get the details of a PEcAn PFT
get.pft(server, pft_id='2000000045')
#> $model_type
#> [1] "SIPNET"
#> $pft_id
#> [1] 2000000045
#> $pft_name
#> [1] "temperate.broadleaf.deciduous"
#> $definition
#> [1] "SIPNET Temperate Deciduous PFT with priors on all parameters"
#> $pft_type
#> [1] "plant"Get Information about PEcAn Formats
Search for PEcAn Formats
search.formats(server, format_name="ameriflux", mimetype="netcdf")
#> $formats
#> mimetype format_id format_name
#> 1 application/x-netcdf 38 AmeriFlux.level2.h.nc
#> 2 application/x-netcdf 1000000005 Ameriflux
#> $count
#> [1] 2Get details about a PEcAn Format
get.format(server, format_id=38)
#> $mimetype
#> [1] "application/x-netcdf"
#> $format_id
#> [1] 38
#> $name
#> [1] "AmeriFlux.level2.h.nc"
#> $notes
#> [1] "Ameriflux Level 2 data files (in netCDF format) ..."
#> $header
#> [1] ""
#> $format_variables
#> description name unit
#> 1 air temperature TA degrees C
#> 2 Wind speed m s-1
#> ...Get Information about PEcAn Inputs
Search for PEcAn Inputs
search.inputs(server, model_id=1000000014, site_id=772, host_id=99000000001)
#> $inputs
#> sitename model_name revision mimetype format_name tag hostname file_name
#> 1 Niwot Ridge Forest/LTER NWT1 (US-NR1) SIPNET r136 text/csv Sipnet.climna met docker niwot.clim
#> 2 Niwot Ridge Forest/LTER NWT1 (US-NR1) SIPNET r136 text/csv Sipnet.climna met docker US-NR1.clim
#> file_path id input_name start_date end_date
#> 1 /data/sites/niwot 99000000003 2002-01-01 2005-12-31
#> 2 /data/sites/niwot 99000000004 1999-01-01 2003-12-31
#> $count
#> [1] 2Download a PEcAn Input File
download.input(server, input_id=99000000003, save_as="niwot.clim.local")This will download the requested input file & save it as niwot.clim.local
Get Information about PEcAn Workflows
Get list of PEcAn Workflows
get.workflows(server, model_id='1000000022', site_id='676')
#> $workflows
#> id folder started_at site_id model_id hostname start_date end_date
#> 1 1000009900 /fs/data2/output//PEcAn_1000009900 2018-11-09 08:56:37 676 1000000022 geo.bu.edu 2004-01-01 2004-12-31
#> 2 1000009172 /fs/data2/output//PEcAn_1000009172 2018-04-11 18:14:52 676 1000000022 test-pecan.bu.edu 2004-01-01 2004-12-31
#> 3 1000010079 /fs/data2/output//PEcAn_1000010079 2018-12-15 12:32:26 676 1000000022 geo.bu.edu 2004-01-01 2004-12-31
#> 4 1000010213 /fs/data2/output//PEcAn_1000010213 2019-02-08 14:38:45 676 1000000022 geo.bu.edu 2004-01-01 2004-12-31
#> 5 1000010172 /fs/data2/output//PEcAn_1000010172 2019-01-13 09:30:18 676 1000000022 geo.bu.edu 2004-01-01 2004-12-31
#> $count
#> [1] 5Get details about a PEcAn Workflow
get.workflow(server, workflow_id='99000000031')
#> $id
#> [1] "1000010213"
#> $folder
#> [1] "/fs/data2/output//PEcAn_1000010213"
#> $hostname
#> [1] "geo.bu.edu"
#> $user_id
#> [1] "NA"
#> $properties
#> $properties$end
#> [1] "2004/12/31"
#> $properties$lat
#> [1] ""
#> $properties$lon
#> [1] ""
#> $properties$pft
#> [1] "boreal.coniferous"
#> $properties$email
#> [1] ""
#> $properties$notes
#> [1] ""
#> $properties$start
#> [1] "2004/01/01"
#> $properties$siteid
#> [1] "676"
#> $properties$modelid
#> [1] "1000000022"
#> $properties$hostname
#> [1] "geo.bu.edu"
#> $properties$sitename
#> [1] "WillowCreek(US-WCr)"
#> $properties$input_met
#> [1] "CRUNCEP.SIPNET"
#> $properties$sitegroupid
#> [1] "1"
#> $properties$input_poolinitcond
#> [1] "-1"
#> $files
#> [1] "pecan.CHECKED.xml" "pecan.CONFIGS.xml"
#> ...Submit a PEcAn Workflow for Execution
Submit a workflow directly using user-specified parameters
submit.workflow(
server,
model_id=1000000014,
site_id=772,
pfts=c("temperate.coniferous"),
start_date="2002-01-01",
end_date="2003-12-31",
inputs=list(
met=list(id=99000000003)
)
)
#> $workflow_id
#> [1] 99000000001
#> $status
#> [1] "Submitted successfully"Submit a workflow as an XML file
This assumes the presence of an XML file test.xml containing the specifications of the workflow.
submit.workflow.xml(server, xmlFile='test.xml')
#> $workflow_id
#> [1] 99000000002
#> $status
#> [1] "Submitted successfully"Submit a workflow as a JSON file
This assumes the presence of a JSON file test.json containing the specifications of the workflow.
submit.workflow.json(server, xmlFile='test.json')
#> $workflow_id
#> [1] 99000000003
#> $status
#> [1] "Submitted successfully"Submit a set of workflows specified as a CSV file
This assumes the presence of a CSV file test.csv containing the specifications of the set of workflows.
Columns: model revision met site_id pft start_date end_date sensitivity ensemble comment
submit.workflows.csv(server, csvFile='test.csv')
#> [[1]]
#> [[1]]$workflow_id
#> [1] "99000000141"
#> [[1]]$status
#> [1] "Submitted successfully"
#> [[2]]
#> [[2]]$workflow_id
#> [1] "99000000142"
#> [[2]]$status
#> [1] "Submitted successfully"Get Information about PEcAn Runs
Get list of Runs belonging to a PEcAn Workflow
get.runs(server, workflow_id='1000009172')
#> $runs
#> runtype ensemble_id workflow_id id model_id site_id parameter_list start_time finish_time
#> 1 ensemble 1000017624 1000009172 1002042201 1000000022 796 ensemble=1 2005-01-01 2011-12-31
#> 2 ensemble 1000017624 1000009172 1002042202 1000000022 796 ensemble=2 2005-01-01 2011-12-31
#> 3 ensemble 1000017624 1000009172 1002042203 1000000022 796 ensemble=3 2005-01-01 2011-12-31
#> 4 ensemble 1000017624 1000009172 1002042204 1000000022 796 ensemble=4 2005-01-01 2011-12-31
#> 5 ensemble 1000017624 1000009172 1002042205 1000000022 796 ensemble=5 2005-01-01 2011-12-31
#> ...
#> $count
#> [1] 50
#> $next_page
#> [1] "http://pecan.localhost:80/api/runs/?workflow_id=1000009172&offset=50&limit=50"Get details about a PEcAn Run
get.run(server, run_id='99000000282')
#> $runtype
#> [1] "sensitivity analysis"
#> $ensemble_id
#> [1] 99000000002
#> $workflow_id
#> [1] 99000000031
#> $id
#> [1] 99000000282
#> $model_id
#> [1] 1000000014
#> $site_id
#> [1] 772
#> $start_time
#> [1] "2002-01-01"
#> $finish_time
#> [1] "2005-12-31"
#> $parameter_list
#> [1] "quantile=15.866,trait=dVPDSlope,pft=temperate.coniferous"
#> $started_at
#> [1] "2020-07-21 21:42:09"
#> $finished_at
#> [1] "2020-07-21 21:43:11"
#> $inputs
#> $inputs$info
#> [1] "README.txt"
#> $inputs$others
#> [1] "sipnet.clim" "sipnet.in" "sipnet.param" "sipnet.param-spatial"
#> $outputs
#> $outputs$logfile
#> [1] "logfile.txt"
#> $outputs$info
#> [1] "README.txt"
#> $outputs$years
#> $outputs$years$`2002`
#> $outputs$years$`2002`$data
#> [1] "2002.nc"
#> $outputs$years$`2002`$variables
#> $outputs$years$`2002`$variables$GPP
#> [1] "Gross Primary Productivity"
#> $outputs$years$`2002`$variables$NPP
#> [1] "Net Primary Productivity"
#> ...Plots & File Downloads for Workflows & Runs
Plot the desired variables from the results of a PEcAn Run
plot_run_vars(
server_invalid,
run_id=99000000283,
year=2002,
y_var="TotalResp",
x_var="SoilResp"
)This will produce a plot.png file containing the requested plot
Download an Input File for a Run
download.run.input(server, run_id=99000000283, filename="sipnet.in", save_as="sipnet.in.local")This will download the requested input file & save it as sipnet.in.local
Download an Output File for a Run
download.run.output(server, run_id=99000000283, filename="2002.nc", save_as="local.2002.nc")This will download the requested output file & save it as local.2002.nc
Download a File for a Workflow
download.workflow.file(server, workflow_id=99000000031, filename="pecan.xml", save_as="local.pecan.xml")This will download the requested file & save it as local.pecan.xml ***
Please note that this package is under active development & some functionality may not be ready to use.