# rwrfhydro
A community-contributed tool box for managing, analyzing, and visualizing WRF Hydro (and HydroDART) input and output files in R.

# Purpose
Intentionally, “rwrfhydro” can be read as “our wrf hydro”. The purpose of this R package is to focus community development of 
tools for working with and analyzing data related to the WRF Hydro model. These tools are both free and open-source, just like
R, which should help make them accessible and popular. For users new to R, several introductory resources are listed below. 

The purposes of this README are 1) to get you started using rwrfhydro and 2) to explain the basics (and then some) of how we 
develop the package so you can quickly start adding your contributions. 

Table of Contents
=================
  * [Installing](#installing)
  * [Using](#using)
  * [Developing](#developing)
    * [Version control for collaboration: Github](#version-control-for-collaboration-github)
      * [Forking](#forking-and-cloning)
      * [devBranch and pull requests](#devbranch-and-pull-requests)  
      * [Not using Github](#not-using-github)
    * [Workflow: git, R packaging, and you](#workflow-git-r-packaging-and-you)
    * [Our best practices](#our-best-practices)
      * [R package best practices and code style](#r-package-best-practices-and-code-style)
        * [Organizing functions](#organizing-functions)
        * [R code style](#r-code-style)
        * [Packages are NOT scripts](#packages-are-not-scripts)
        * [Documentation with roxygen](#documentation-with-roxygen)
      * [Objects in rwrfhydro](#objects-in-rwrfhydro)
      * [Graphics](#graphics)
  * [R Package development resources](#r-package-development-resources)
  * [Introductory R resources](#introductory-r-resources)

# Installing
Installing the development package (not on [CRAN](http://cran.r-project.org/)) is facilitated by the devtools package (on CRAN),
so devtools is installed in this process. The following is done for the initial install or to update the rwrfhydro package.
``` R
install.packages("devtools")
devtools::install_github("mccreigh/rwrfhydro")
```
The very first time this is run, it can take a while to install all the package dependencies listed as "Imports" in the
[DESCRIPTION](https://github.com/mccreigh/rwrfhydro/blob/master/DESCRIPTION) file. 

To check for updates (to the master branch) once rwrfhydro is loaded run `CheckForUpdates()`. 

To install other branches than master and perhaps from your own fork:
``` R
devtools::install_github("username/rwrfhydro", ref='myBranch')
```
Note that `CheckForUpdates()` will always tell you there are updates if you are using a different branch than master. 

# Using
After the one-time install or any subsequent re-installs/updates, simply load the rwrfhydro library in an R session:
```
library(rwrfhydro)
```
and now the package (namespace) is available. 

[*Online vignettes*](https://github.com/mccreigh/rwrfhydro/blob/master/vignettes.Rmd) (or in R `browseVignettes("rwrfhydro")`) are probably the easiest way to get in-depth, thematic overviews of rwrfhydro functionality.

To get package metadata and a listing of functions:  `library(help=rwrfhydro)`. Just the functions: `ls('package:rwrfhydro')`.
For specific functionality see function help (e.g. `?VisualizeDomain` or `help(VisualizeDomain)`). 

# Developing

There are three main aspects of developing the code base and contributing:

* Version control for collaboration: Again, not terribly interesting but incredibly useful. For those new to the Git/Github process, it can be a bit daunting. Please contact us for some help, we do want to get your useful code into the main repository!

* R Packaging: Not very interesting, but critical for creating the extrememly useful nature of R packages. Fortunately, the `devtools` package simplifies life tremendously and so figures prominently in the development process we sketch below.

* Our best practices: This ranges from fundamental to fussy. 

All of these topics (minus some of our specific best practices) are treated by [Hadley Wickham’s book on R Packages](http://r-pkgs.had.co.nz/). Specific sections of this book are linked below. Further resources on R package development are listed below. 

## Version control for collaboration: Github
Note that devtools::install_github() installs rwrfhydro into you default library path (`.libPaths()[1]`) and that the sources code 
is not included. To edit the source, code you can download from github or you can actually fork and clone the repository to your 
machine of choice. Note that your git repository is not in your default library path, but somewhere else. Using devtools, however, 
allows you to load the development package similarly to as if it were a package in your library path (with some slight differences). 
This means that after you add some code locally, you can load rwrfhydro with those changes appearing packaged. The basic use of 
devtools is outlined below. It greatly stream lines all aspects of developing R packages and is highly recommended. Note we 
recommend that you install rwrfhydro using devtools::install_github() first, because this streamlines the installation of package 
dependencies. 

### Forking and cloning
Please fork the repository to contribute. A fork is a separate copy of the main repository. 
[Forking is trivial in Github](https://help.github.com/articles/fork-a-repo/).
You have to have a free (for open-source repositories) account to fork on github.

Then you'll clone the fork to a local computer and you'll have to interact between the github version, 
which is used to send pull requests to the main repository, and your local version. We give some tips below. 
Keep your fork sync'd as much as possible to avoid painful merges.  

### devBranch and pull requests
We maintain two branches: master and devBranch. devBranch is where pull requests go. Changes go to master, theoretically, after
they've been tested on devBranch. And that's done by "mccreigh".

We ask that you send pull requests for the devBranch branch in the repository (and NOT the master). How you get your code
into the devBranch is your choice. The easiest way is to `git checkout devBranch` before you do anything.

When you have a piece of code to add to the master, [send a pull request](https://help.github.com/articles/using-pull-requests/). 
We give more details on using git in the [workflow](#workflow-git-r-packaging-and-you) overview below.

### Not using Github.
hmm..., expand on this: http://stackoverflow.com/questions/4728432/git-forking-without-github

## Workflow: git, R Packaging, and you

Workflow is approximately this:
  
* Fork project
* Development cycles:
  * Checkout the devBranch (`git checkout devBranch`)
  * Optional: Make a topic branch of devBranch in git (e.g. `git checkout newBranch`)
  * Write code (in these dirs: R/, NAMESPACE, src/, data/, inst/).
  * Write documentation (in these dirs: man/, vignettes/).
  * Write tests (in this dir: test/).
  * Check with devtools: `devtools::document(); devtools::check_doc(); devtools::check()`
  * Commit to your branch with git. (`git commit -am 'Some cool features were needed.'`)
  * Merge your master with the upstream repository to minimize merge pains. 
  ([See here.](https://help.github.com/articles/syncing-a-fork/) Note pushing back to github at the very bottom.)
  * Merge your devBranch with your master. (`git checkout devBranch; git merge master`)
  * Push your devBranch to github. (`git push origin devBranch`)
  * Submit a [pull request on github](https://help.github.com/articles/using-pull-requests/) on devBranch. 


## Our best practices

### R package best practices and code style
[http://r-pkgs.had.co.nz/r.html](http://r-pkgs.had.co.nz/r.html)

#### Organizing functions
[http://r-pkgs.had.co.nz/r.html#r-organising](http://r-pkgs.had.co.nz/r.html#r-organising)
* Do NOT put all functions in a single file, nor each in their own file. Functions should be grouped by files and may occasionally need moved to new or different files as new functions are written.
* File names end in .R and are all lowercase with _ used to separate words. (All lowercase (except the .R) helps ensure compatibility with Windows developers.)

#### R code style
[http://r-pkgs.had.co.nz/r.html#style](http://r-pkgs.had.co.nz/r.html#style)
* Generally follow Google’s R style guide with preference for variableName (first-lower camel case) over variable.name (period distinction). Note that functions are first-upper camel case, e.g. FunctionName.  [https://google-styleguide.googlecode.com/svn/trunk/Rguide.xml](https://google-styleguide.googlecode.com/svn/trunk/Rguide.xml)
* Variables are nouns. Functions are verbs.
* Lots of other style considerations to learn: indents, braces, line length, assignment, comment style.

#### Packages are NOT scripts
[http://r-pkgs.had.co.nz/r.html#r-differences](http://r-pkgs.had.co.nz/r.html#r-differences)
* Don’t use library() or require(). Use the DESCRIPTION to specify your package’s requirements.
* Use package::function() to use function from external packages. Make sure the package and version are listed in DESCRIPTION.
* Never use source() to load code from a file. Rely on devtools::load_all() to automatically source all files in R/.
* Don’t modify global options() or graphics par(). Put state changing operations in functions that the user can call when they want.
* Don’t save files to disk with write(), write.csv(), or saveRDS(). Use data/ to cache important data files.

#### Documentation with roxygen
[http://r-pkgs.had.co.nz/man.html](http://r-pkgs.had.co.nz/man.html)
* Roxygen comments start with #' and come before a function. All the roxygen lines preceding a function are called ablock. Each line should be wrapped in the same way as your code, normally at 80 characters.
* Blocks are broken up into tags, which look like @tagName details. The content of a tag extends from the end of the tag name to the start of the next tag (or the end of the block). Because @ has a special meaning in roxygen, you need to write @@ if you want to add a literal @ to the documentation (this is mostly important for email addresses and for accessing slots of S4 objects).
* Each block includes some text before the first tag. This is called the introduction, and is parsed specially:
* The first sentence becomes the title of the documentation. That’s what you see when you look at help(package = mypackage) and is shown at the top of each help file. It should fit on one line, be written in sentence case, and end in a full stop.
* The second paragraph is the description: this comes first in the documentation and should briefly describe what the function does.
* The third and subsequent paragraphs go into the details: this is a (often long) section that is shown after the argument description and should go into detail about how the function works.
* All objects must have a title and description. Details are optional.

### Objects in rwrfhydro
We will probably need to develop some s3 classes or reuse some from other packages.
List of possible objects:
gaugePts object for organizing "frxst points", both locations and data.

### Graphics
We need to resolve if we are going to use base graphics or ggplot or both. 
I’m leaning towards both. Not all plotting routines have to always be available for a given function, but I think that both will probably develop over time. 




Because ggplot has a big learning curve, we can return closures which 1) provide tweakability for basic things to be adjusted in the plot make the plot when called, 2) which return the basic ggplot object which can then also be extended with ggplot commands. I made an example of this in VisualizeDomain.R for ggmap/ggplot objects.

# R Package development resources
* [http://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/](http://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/)
* [http://r-pkgs.had.co.nz/](http://r-pkgs.had.co.nz/)
* [http://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf](http://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf)
* [http://portal.stats.ox.ac.uk/userdata/ruth/APTS2012/Rcourse10.pdf](http://portal.stats.ox.ac.uk/userdata/ruth/APTS2012/Rcourse10.pdf)

# Introductory R resources (somewhat random)
* [My introduction to R: multiple resources but, sorry, the video link is broken.] (https://nex.nasa.gov/nex/resources/118/) 
* [My R cheat sheet (also availabile in LaTex inthe above link).] (https://nex.nasa.gov/nex/static/media/other/R-refcard_2.pdf)
* [The popular YouTube serires on R by Roger Peng.] (https://www.youtube.com/user/rdpeng)
* [https://www.datacamp.com/courses/free-introduction-to-r] (https://www.datacamp.com/courses/free-introduction-to-r)
* [http://cran.r-project.org/doc/contrib/Torfs+Brauer-Short-R-Intro.pdf] (http://cran.r-project.org/doc/contrib/Torfs+Brauer-Short-R-Intro.pdf)
* [http://cran.r-project.org/doc/manuals/R-intro.pdf] (http://cran.r-project.org/doc/manuals/R-intro.pdf)