36 PEcAn Hands-On Demo 01: Basic Run

36.1 Objective

We will begin by exploring a set of web-based tools that are designed to run single-site model runs. A lot of the detail about what’s going on under the hood, and all the outputs that PEcAn produces, are left to Demo 2. This demo will also demonstrate how to use PEcAn outputs in additional analyses outside of PEcAn.

36.1.1 PEcAn URL

In the following demo, URL is the web address of a PEcAn server and will refer to one of the following:

  • If you are doing a live demo with the PEcAn team, URL was provided
  • If you followed instructions in Download the PEcAn VM , URL = localhost:6480
  • If you running PEcAn [Using AmazonWeb Services], URL is the Public IP
  • If you followed instructions found in Install PEcAn by hand, URL is your server’s IP

36.2 Basic Run

36.2.1 Start PEcAn:

  1. Enter URL in your web browser
  2. Click “Run Models”
  3. Click the ‘Next’ button to move to the “Site Selection” page.

36.2.2 Site Selection

36.2.3 Host

Select the local machine “pecan”. Other options exist if you’ve read and followed instructions found in Remote execution with PEcAn.

36.2.4 Mode

Select SIPNET (r136) from the available models because it is quick & simple. Reference material can be found in Models in PEcAn

36.2.5 Site Group

To filter sites, you can select a specific group of sites. For this tutorial we will use Ameriflux.

36.2.6 Conversion:

Select the conversion check box, to show all sites that PEcAn is capable of generating model drivers for automatically. By default (unchecked), PEcAn only displays sites where model drivers already exist in the system database

36.2.7 Site:

For this tutorial, type US-NR1 in the search box to display the Niwot Ridge Ameriflux site (US-NR1), and then click on the pin icon. When you click on a site’s flag on the map, it will give you the name and location of the site and put that site in the “Site:” box on the left hand site, indicating your current selection.

Once you are finished with the above steps, click “Next”.

36.2.7.1 Run Specification

Next we will specify settings required to run the model. Be aware that the inputs required for any particular model may vary somewhat so there may be addition optional or required input selections available for other models.

36.2.7.2 PFT (Plant Functional Type):

Niwot Ridge is temperate coniferous. Available PFTs will vary by model and some models allow multiple competing PFTs to be selected. Also select soil to control the soil parameters

36.2.7.3 Start/End Date:

Select 2003/01/01 to 2006/12/31. In general, be careful to select dates for which there is available driver data.

36.2.7.4 Weather Data:

Select “Use AmerifluxLBL” from the Available Meteorological Drivers.

36.2.7.5 Optional Settings:

Leave all blank for demo run

  1. Email sends a message when the run is complete.
  2. Use Brown Dog will use the Brown Dog web services in order to do input file conversions. (Note: Required if you select Use NARR for Weather Data)
  3. Edit pecan.xml allows you to configure advanced settings via the PEcAn settings file
  4. Edit model config pauses the workflow after PEcAn has written all model specific settings but before the model runs are called and allows users to configure any additional settings internal to the model.
  5. Advanced Setup controls ensemble and sensitivity run settings discussed in Demo 2.

Finally, click “Next” to start the model run.

36.2.7.6 Data Use Policies

You will see a data policy statement if you selected a data source with a policy. Agreeing to the policy is required prior to starting the run.

36.2.7.7 If you get an error in your run

If you get an error in your run as part of a live demo or class activity, it is probably simplest to start over and try changing options and re-running (e.g. with a different site or PFT), as time does not permit detailed debugging. If the source of the error is not immediately obvious, you may want to take a look at the workflow.Rout to see the log of the PEcAn workflow or the logfile.txt to see the model execution output log and then refer to the Documentation or the Chat Room for help.

36.2.8 Model Run Workflow

36.2.8.1 MET Process:

First, PEcAn will download meteorological data based on the type of the Weather Data you chose, and process it into the specific format for the chosen model

36.2.8.2 TRAIT / META:

PEcAn then estimates model parameters by performing a meta-analysis of the available trait data for a PFT. TRAIT will extract relevant trait data from the database. META performs a hierarchical Bayes meta-analysis of available trait data. The output of this analysis is a probability distribution for each model parameter. PEcAn selects the median value of this parameter as the default, but in Demo 2 we will see how PEcAn can use this parameter uncertainty to make probabilistic forecasts and assess model sensitivity and uncertainty. Errors at this stage usually indicate errors in the trait database or incorrectly specified PFTs (e.g. defining a variable twice).

36.2.8.3 CONFIG:

writes model-specific settings and parameter files

36.2.8.4 MODEL:

runs model.

36.2.8.5 OUTPUT:

All model outputs are converted to standard netCDF format

36.2.8.6 ENSEMBLE & SENSITIVITY:

If enabled post-process output for these analyses

If at any point a Stage Name has the Status “ERROR” please notify the PEcAn team member that is administering the demo or feel free to do any of the following:

  • Refer to the PEcAn Documentation for documentation
  • Post the end of your workflow log on our Gitter chat
  • Post an issue on Github.

The entire PEcAn team welcomes any questions you may have!

If the Finished Stage has a Status of “DONE”, congratulations! If you got this far, you have managed to run an ecosystem model without ever touching a line of code! Now it’s time to look at the results click Finished.

FYI, adding a new model to PEcAn does not require modification of the model’s code, just the implementation of a wrapper function.

36.2.8.7 Output and Visualization

For now focus on graphs, we will explore all of PEcAn’s outputs in more detail in Demo 02.

36.2.8.8 Graphs

  1. Select a Year and Y-axis Variable, and then click ‘Plot run/year/variable’. Initially leave the X-axis as time.
  2. Within this figure the points indicate the daily mean for the variable while the envelope encompasses the diurnal variability (max and min).
  3. Variable names and units are based on a standard netCDF format.
  4. Try looking at a number of different output variables over different years.
  5. Try changing the X-axis to look at bivariate plots of how different output variables are related to one another. Be aware that PEcAn currently runs a moving min/mean/max through bivariate plots, just as it does with time series plots. In some cases this makes more sense than others.

36.2.8.9 Alternative Visualization: R Shiny

  1. Click on Open SHINY, which will open a new browser window. The shiny app will automatically access your run’s output files and allow you to visualize all output variables as a function of time.

  1. Use the pull down menu under Variable Name to choose whichever output variable you wish to plot.

36.2.8.10 Model Run Archive

Return to the output window and Click on the HISTORY button. Click on any previous run in the “ID” column to go to the current state of that run’s execution – you can always return to old runs and runs in-progress this way. The run you just did should be the more recent entry in the table. For the next analysis, make note of the ID number from your run.

36.3 Next steps

36.3.0.0.1 Analyzing model output

Follow this tutorial, [Analyze Output] to learn how to open model output in R and compare to observed data

36.3.0.1 DEMO 02

Demo 02: Sensitivity and Uncertainty Analysis will show how to perform Ensemble & Sensitivity Analyses through the web interface and explore the PEcAn outputs in greater detail, including the trait meta-analysis