r-forks-to-learn / bcgovr

An R package to automate set up and sharing of R projects in bcgov GitHub following bcgov guidelines

bcgovr

Overview

An R package to support development of R-based projects and packages following bcgov open source guidelines and policies.

Features

Currently there are two main functions for auto-populating a new R-based data analysis or package project directory with folders & files that encourage best practice in scientific computing and ensure the project has all the required bcgov items:

• analysis_skeleton() # starting a new data analysis project
• package_skeleton() # starting a new R package

These functions are most easily used by using the bcgovr Project Template as described below.

Addins

The package also installs two RStudio Addins for adding:

1. The boiler-plate Apache 2.0 license header into the comments header of every source code file.
2. A BCDevExchange project state badge to a README file.

Installation

Once you have R & RStudio installed on your machine, open up RStudio so you can install the bcgovr package directly from this GitHub repository. To do so, you will first need the devtools package:

install.packages("devtools")

Next, install and load the bcgovr package using devtools::install_github():

devtools::install_github("bcgov/bcgovr")
library(bcgovr)

Usage

RStudio Addins

Apache 2.0 License Header

Need to add that Apache 2.0 license header to a new .R file? Just click-click:

BCDevExchange Project State Badge

Need to add a project state badge to your .md or .Rmd file? Just click-click-click:

Analysis and Package Templates

bcgovr allows you to set up a new R-based open source data analysis project (or package) with folders & files that encourage best practice in scientific computing and including all of the required bcgov items.

The easiest way to set up a new project is to use the bcgovr project template through RStudio:

Step 1: Set up a remote repository

For a remote in github.com/bcgov, click on the green New button to create a new repository. Choose a repository name—our example repository name is bcgovr_analysis. You should open an empty repository—without initializing a README, a .gitignore file or a license—as bcgovr will take care of all of that for you later. Copy the URL of the repository, you'll need it to set up your local repository in the next step.

Step 2: Set up & populate local repository using bcgovr

RStudio GUI users: Open a fresh session of RStudio. Start a New Project: New Project -> New Directory -> BC Gov Analysis/Package Skeleton. Confirm local location of your new project in the Directory Name field, and paste the URL of the github.com/bcgov repository from step 1 in the Repository URL field. Check/uncheck, and fill in the other fields as relevant to your project, and Click 'Create Project'. The bcgov template files and folders will be created in the new directory, and your local project is now "connected" to your remote in github.com/bcgov. For different folder templates, see the Options section below.

The result is a bcgov 'ready-to-go' local directory for a new data analysis project:

Step 3: Stage, Commit & Push local repository folders & files to remote repository

RStudio GUI users: Now you are ready to Stage, Commit & Push changes in your local repository to the remote repository in github.com/bcgov. Using the functions in the Git tab in RStudio, you can Stage your changes by selecting files, Commit the staged changes---including informative commit messages---and Push the changes to the remote repository. Remember to make use of the .gitignore file for files & folders you do not want to keep under version control (e.g. outputs or source data sets), and to use the Pull function before you start work to ensure your local repository is up-to-date with the remote repository.

Git Command Line Users: Stage, Commit & Push changes in your local repository to the remote repository in github.com/bcgov using the Command Line (e.g. Git Bash or Terminal).

git status # see what file(s) are new or have changed
git add README.md # stage the README file
git commit -m "First commit of README file" # commit the file with an informative message
git push origin master # push the changes in your local repository up to the remote repository

You can use the Command Line to confirm or add the remote url for an existing local project. Checkout GitHubHelp for more resources for using Git and the Command Line. The Happy Git and GitHub for the useR e-book is a great, free resource for learning and using Git and GitHub with R.

git remote -v # verifies the new remote URL
git remote add origin https://github.com/bcgov/bcgovr_analysis.git # sets the remote

Options

There are several options you can specify in your .Rprofile file to customise the default behaviour when creating analysis projects and packages with bcgovr:

• bcgovr.coc.email: Code of Conduct contact email address

• bcgovr.dir.struct: Alternative analysis directory structure. This should be specified as a character vector of directory and file paths (relative to the root of the project). Directories should be identified by having a trailing forward-slash (e.g., "dir/").

  The default is: c("R/","out/", "graphics/", "data/", "01_load.R", "02_clean.R", "03_analysis.R", "04_output.R", "internal.R", "run_all.R").

To make use of these options, there should a section in your .Rprofile file that looks something like this:

if (interactive()) {
    options("bcgovr.coc.email" = "[email protected]")
    options("bcgvor.dir.struct" = c("doc/", "data/", "bin/", "results/", "src/01_load.R", "src/02_clean.R",
            "src/03_analysis.r", "src/04_output.R", "src/runall.R"))
} 

Project Template Functions

analysis_skeleton

As an alternative to using the 'New Project -> ...' dialogue in RStudio, you can use the R console and bcgovr::analysis_skeleton() to create a new local project. You can specify the URL of the remote repository (from step 1 above) using the git_clone argument. Be sure to either specify your new analysis local directory using the path argument, or setwd("C:/my_bcgov_analysis") before running analysis_skeleton(). Type ?analysis_skeleton in the R console for help.

bcgovr::analysis_skeleton(path = "C:\_dev\bcgovr_analysis", git_clone = "url of remote repository") 

package_skeleton

The package_skeleton() function is used the same way as analysis_skeleton() but will create all the files & folders to get started on creating an R package. Type ?package_skeleton in the R console for help. The R packages book by Hadley Wickham is an incredible resource if you are looking to create packages.

Project Status

This package is under active development.

Getting Help or Reporting an Issue

To report bugs/issues/feature requests, please file an Issue.

How to Contribute

If you would like to contribute to the package, please see our CONTRIBUTING guidelines.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

Copyright 2017 Province of British Columbia

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at 

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

This repository is maintained by Environmental Reporting BC. Click here for a complete list of our repositories on GitHub.