GRAN

What is GRAN?

Geological Survey R Archive Network

GRAN is a repository of curated R packages developed by USGS employees for USGS and external use. It allows a user to easily download and install an R package and, in the future, receive updates to that package code as they become available. Inclusion of packages on GRAN does not imply USGS approval; citations and disclaimers associated with package are included upon package load or in the package "CITATION" file.

The objective of GRAN is to facilitate engagement and R tool sharing across the USGS Water Mission Area.

How to use GRAN?

There are two ways to take advantage of GRAN tools.

  1. Alter the .Rprofile file

    This will tell your R environment to always look in the GRAN repository when installing packages and updating packages. This is the preferred method because of the ability to automatically get GRAN updates. The following command in R will run a script to update your Rprofile file:
  2. 
    rprofile_path = file.path(Sys.getenv("HOME"), ".Rprofile")
    write('\noptions(repos=c(getOption(\'repos\'),
        CRAN=\'https://cloud.r-project.org\',
        USGS=\'https://owi.usgs.gov/R\'))\n',
          rprofile_path, 
          append =  TRUE)
    
    cat('Your Rprofile has been updated to include GRAN.
        Please restart R for changes to take effect.')
    
    
    It is then possible to simply install the smwrData package using:
    
    install.packages("smwrData")
    
    
    Or to update all installed packages (if needed) with:
    
    update.packages()
    
    
  3. Use the 'repo' argument in the install.packages function

    This will tell install.packages to look at a specific url for package installation.
  4. 
    install.packages("smwrData", repos=c("https://owi.usgs.gov/R",getOption("repos")))
    
    

What packages are on GRAN?

GRAN includes curated packages that can be easily installed. A detailed package list will be added in the future, but one can always use the following command in R to list all packages that are currently available:

    
    GRAN_pkg <- available.packages(contrib.url("https://owi.usgs.gov/R"))
    names(GRAN_pkg[,1])
    
    

How do I add my package to GRAN?

Developers that have an R package that would be useful to others within USGS are encouraged to use GRAN to distribute those packages. There are a minimum number of required steps before a package is GRAN-ready (see guidelines), which should be completed before submitting a package to GRAN. Assuming a package is compliant, follow the steps for submission below:

  1. Obtain, document, and address peer review of package using the my.usgs JIRA system.
  2. Host your full package code on GitHub (preferably within the USGS-R organization)
  3. Create a tagged release of a stable version of your package on github.com
  4. Ensure package builds and passes "as cran" checks with no warnings
    
    R CMD check --as-cran {packagename_version}.tar.gz
    
    
  5. Fork the USGS-R grantools to your USGS GitHub account.
  6. Add your package location and name (using the format repository/packagename) and tagged release name to the file gran_source_list.tsv
  7. Create a pull request between your fork of grantools and the USGS-R version of grantools
  8. Packages are expect to have zero Notes or Warnings on check. If you would like an exception, explain (in the pull request comments) why each Note and Warning should be allowed.
  9. Receive a notification once your package has been added (usually within one day).

What are the GRAN guidelines?

  1. Required: Active tool maintainer with *@usgs.gov email address If a maintainer becomes inactive, the package will be removed.
  2. Required: Code must be on GitHub USGS-R repository to facilitate the automation of tool builds, checks, and releases:
    • Required: Each GRAN update must be a Github "release".
    • Recommended: Continuous integration.
    • Recommended: Maintainer will use Github issues system for issue/bug reporting and tracking.
  3. Required: All packages must either print the OWI GRAN Software disclaimerA or a link to the appropriate package category. This is only required for packages that do not have an associated peer-reviewed publication and citation. For example:
  4. 
    .onAttach <- function(libname, pkgname) {
      packageStartupMessage(paste(strwrap(
      'USGS Support Package: 
      https://owi.usgs.gov/R/packages.html#support'),
      collapse='\n'))
    }
    
    

    Which will show the user:

    
    library(smwrGraphs)
    USGS Support Package: 
    https://owi.usgs.gov/R/packages.html#support
    
    
  5. Required: All packages with a peer-reviewed publication must include proper reference in the package "CITATION" file.
  6. Once a CITATION is included, there is no requirement for the package startup message as described above.

  7. Initial code import and updates are handled through pull requests to "grantools". New GRAN users should contact <gs-w_r_admin@usgs.gov> for support with initial release of software.
  8. Binary packages will be maintained for only the current release version of R.
  9. Package maintainers are expected to understand and follow the policies of the USGS for code distribution. Water Policy 2009.01 and Review and Approval of Software for Release.
  10. USGS best practices for software are described here.

A OWI GRAN Software disclaimer: This software is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The software has not received final approval by the U.S. Geological Survey (USGS). No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software.