3 About the PEcAn Book

This book serves as documentation for the PEcAn Project. It contains descriptions of topics necessary to inform a beginner and advanced user as well as requisite materials for developers. It does not contain low-level descriptions of functions within PEcAn. Our aim for this documentation is to educate you about the PEcAn software, the possibilities of its usage, and the standards,expectations, and core workflows for developers.

This book is organized four main topics:

Introduction - Brief explanation of PEcAn, how to obtain the PEcAn VM, and explanation of basic web interface functions.

Tutorials/Demos/Workflows - All User and Developer tutorials/demos/workflows to explain how to use and add to PEcAn in different ways.

Topical Pages - Explanation of main PEcAn components and how they fit together.

Appendix - External documentation and sources of information and a FAQ section.

3.1 General Feedback/Comments/Suggestions

We want your ideas, thoughts, comments, and suggestions! As a community we are committed to creating an inclusive and supportive atmosphere so we all to reach out to us in the following ways:

Github: https://github.com/PecanProject/pecan This is the main hub of communication surrounding PEcAn development. Check out the issues section to see known bugs, upcoming features, and ideas for future development. Feel free to comment on existing issues or open new ones with questions, bug reports, feature requests, and/or ideas.

Slack: https://pecanproject.slack.com/ Slack serves as our day to day mode of communication. To join us in slack you will need to create an account first. This is done in 3 steps:

  1. Request an inivitation to join Slack, this will be send by email to address you provided.
  2. Check your inbox for an email from Slack with subject “Rob Kooper has invited you to join a Slack workspace”. This email should have a link that you can click to join slack.
  3. When you click a webpage will open up that asks you to create an account, once that is done you can login into the slack chatrooms.

Email: pecanproj[at]gmail.com If you do not wish your communication with the team to be public, send us an email at the address above and we will get back to you as soon as possible.

3.2 Editing this book

The file organization of this documentation can be described simply as follows:

  • Each chapter is in its own file (within the corresponding section).
  • Each group of chapters (i.e. “part” in LaTeX) is in its own directory.

Sections and chapters are rendered (and numbered) in alpha-numerical order of their corresponding file names. Therefore, each section directory and chapter file name should be prefixed with a two-digit (zero-padded) number. File and directory names should be as similar as possible to the name of the corresponding chapter or section. For instance, the file name for this chapter’s source file is 06_reference/10_editing_this_book.Rmd. This numbering means that if you need to create an additional chapter before an existing one, you will have to renumber all chapters following it.

To ensure correct rendering, you should also make sure that each chapter starts with a level 1 heading (# heading). For instance, this chapter’s source starts with:

Furthermore, to keep the organization consistent, each chapter should have exactly one level 1 heading (i.e. do not combine multiple chapters into a single file). In other words, do not spread a single chapter across multiple files, and do not put multiple chapters in the same file.

Each section directory has a file starting with 00 that contains only the section (or “Part”) title. This is used to create the greyed-out section headers in the rendered HTML. For instance, this section has a file called 00_introduction.Rmd which contains only the following:

To cross-reference a different section, use that section’s unique tag (starts with #; appears next to the section heading surrounded in curly braces). For instance, the following Markdown contains two sections that cross-reference each other:

If no header tag exists for a section you want to cross-reference, you should create one. We have no strict rules about this, but it’s useful to have tags that give some sense of their parent hierarchy and reference their parent sections (e.g. #models, #models-ed, and #models-ed-xml to refer to a chapter on models, with a subsection on ED and a sub-subsection on ED XML configuration). If section organization changes, it is fine to move header tags, but avoid altering existing tags as this will break all the links pointing to that tag. (Note that it is also possible to link to section headings by their exact title. However, this is not recommended because these section titles could change, which would break the links.)

When referring to PEcAn packages or specific functions, it is a good idea to link to the rendered package documentation. For instance, here are links to the models/ed package, the PEcAn.ED2::modify_ed2in function, and the PEcAnRTM package vignette. If necessary, you can also link directly to specific lines or blocks in the source code on GitHub, like this. (To get a link to a line, click its line number. To then select a block, shift-click another line number.)

To insert figures, use knitr::include_graphics("path/to/figure.png") inside an R code chunk. For example:


Note that image file names are relative to the book_source directory, NOT to the markdown file. In other words, if myimage.png was in the same directory as this file, I would still have to reference it as 06_reference/myimage.png – I could not just do myimage.png. The size, caption, and other properties of the rendered image can be controlled via chunk options.

For additional information about how bookdown works (including information about its syntax), see the Bookdown free online book.

3.3 How to create your own version of Documentation

To create your own version of documentation you’ll need to follow these steps: These procedures assume you have an github account, you forked pecan, you have cloned pecan locally, and have a TRAVIS account. 1. Create a repository under your github account with the name “pecan-documentation”. Clear it of any files. Set up the repository with Github Pages by going to the settings tab for that repository. 2. Create a personal access token for github: https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line and copy it. 3. Create a TRAVIS environment variable called GITHUB_PAT and save the access token you made as a secret variable. 4. Create a branch from your local pecan repository with a name that starts with release/. (ie. Release/vtonydoc) 5. Make whichever changes you would like to the documentation and push it up to your fork.

From here TRAVIS will build your documentation. The web version of your documentation will be rendered with the url following the structure: username.github.io/pecan-documentation/pattern_after_release/