USGS-R Packages

Clear communication about package expectations is very important. Package developers should be transparent about the maintenance, development, and user support associated with their package so that potential users are aware. To help with this communication for USGS R packages, we have created the following categories:

  • Core: Widely used and carefully designed
  • Research: More narrow usage and limited long-term support.
  • Support: Limited users with high-impact needs.
  • Orphan: Packages looking for a maintainer and support.

Each is described in detail below. In general, they go from most support and outreach ("Core") to least ("Orphan"). See also the maintenance section in our "R-package development" training: for a deeper conversation on additional package considerations.

USGS Core

A package with the designation "Core" has several key features:

  • Critically important to a wide and general audience
  • Published, peer-reviewed documentation on the package
  • A statement of long-term support should be included in the README. This should communicate the source, timeline, and extent of support.
  • For example:

    1. Source, e.g., "USGS Water Mission Area"
    2. Timeline, e.g., "funding is stable through FY18 and is likely to be renewed into FY19 and beyond"
    3. Extent, e.g., "funding is available for new features, with priorities determined by the development team"

  • Reasonable effort to make prompt responses for the following:
    • Bug fixes
    • R version upgrades
    • Upstream R-package dependency change
    • User support and troubleshooting

    We recommend that maintainers attempt to acknowledge bugs and other issues as soon as they are discovered via a standard public channel such as a GitHub Issue. Then, publicly track the work, giving estimates of time and effort along the way.

  • An active USGS employee is designated as maintainer
  • Development and maintenance of core packages should include a team of developers. Maintainers coordinate and lead the development team, but should not be the sole developer. This increases the Bus Factor ("many individuals know enough to carry on and the project could still succeed even in very adverse events").
  • The package is well tested
  • For example, all critical functions should be tested for expected results using the testthat package. The coverage of testing can be measured using the coveralls or codecov services.

  • The package should be tested on a continuous integration platform regularly. A few example continuous integration platform services are Travis CI, and AppVeyor
  • All external functions have clear documentation and working examples

A user of USGS core packages can expect prompt feedback from bug reports and general-use questions. Users can expect smooth transitions of maintainers since the package is well-tested, well-documented, and multiple developers have collaborated on the project. Enhancements should be carefully considered, "scope-creep" should be actively avoided (that is, give careful thought to adding new features). The general scope of the package should not change over time.

Example Core Packages

Research

Research packages have two distinct phases: Development and Archive. Published but still active packages can seamlessly flow between Archive and Development, with expectations that the relevant requirements from both categories are fulfilled.

The following disclaimer applies to all research packages that do not have an associated peer-reviewed article included in a CITATION file.

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.

Refer to https://www2.usgs.gov/fsp/fsp_disclaimers.asp for more information.

Development

Package development may include an exploratory phase when it's unclear whether an idea will ever become an active, publicly supported package. These packages should remain on personal github repositories or local computers. These packages offer value to only a small number of people for a limited time.

A more mature package during active development has several key features:

  • The package is in active development and there is no guarantee of future behavior.
  • An official disclaimer is shown on the README, and any vignette
  • The package startup message needs to either include the above disclaimer, or link to this page:
  • 
    .onAttach <- function(libname, pkgname) {
      packageStartupMessage(paste(strwrap(
      'USGS Research Package: 
      https://owi.usgs.gov/R/packages.html#research'),
      collapse='\n'))
    }
    
    

    Which will show the user:

    
    library(toxEval)
    USGS Research Package: 
    https://owi.usgs.gov/R/packages.html#research
    
    
  • The development of the package is being driven by a research topic, and should include input from both researchers and software developers.
  • The end goal should be one or more peer-reviewed journal publications.
  • A statement of support should be included in the README. This should communicate the source, timeline, and extent of support.
  • For example:

    1. Source, e.g., "Water Mission Area"
    2. Timeline, e.g., "funding is stable through FY17 and might be renewed into FY18 and beyond"
    3. Extent, e.g., "funding is available for new features, with priorities determined by the development team" or "support is primarily for maintenance rather than new features" or "support covers maintenance and bug fixes, but we're awfully short on time for user questions, sorry"

  • It is encouraged to include a "sunset" date in the README or package startup message.
  • 
    .onAttach <- function(libname, pkgname) {
      packageStartupMessage(paste(strwrap(
      'USGS Research Package: 
    https://owi.usgs.gov/R/packages.html#research
    Funding for toxEval expires summer 2017, 
    after which bug fixes & new features will be minimal'),
      collapse='\n'))
    }
    
    

    Which will show the user:

    
    library(toxEval)
    USGS Support Package: 
    https://owi.usgs.gov/R/packages.html#support
    Funding for toxEval expires summer 2017, 
    after which bug fixes & new features will be minimal
    
    
    
  • Emphasis should still be placed on testing key features and good documentation during development.
  • Since the goal is a published article, the expectation should be that outside users will use this package to test the reproducibility of the primary author’s data analysis, as well as reproducing the analysis on new data.
  • During development, the package version should remain below v1.0.0.

It is important to clearly communicate to any known or unknown users the risk they take with using a package that is in the active research development phase. See ?packageStartupMessage to learn how to add a message to that gets displayed whenever a user loads the package.

Example Research Packages

Archive

A package that has completed the main development concluding with a published document can be archived. Archive packages have several key features:

  • The development of the package was completed with the publishing of a scientific, peer-reviewed journal or report
  • A reproducible work-flow is included either within a vignette or via the final product (such as the journal article)
  • There are no official expectations that bug fixes and R version upgrades will happen. The expectations need to be clearly communicated to the users
  • The package maintainer should have an active email.
  • The package version should be updated to v1.0.0 once a stable version is released.
  • Once the final version is released, the maintainer should provide the output of devtools::session_info() for an archive of the environment in which the code was last tested and verified as stable.

It should be clearly communicated that the package has a well-documented final product. An archived research R-package can certainly maintain development such as bug fixes and required changes to R version updates. Maintaining the package and interacting with users can be very beneficial for professional development. However, it is important to communicate the official level of support for future users. See ?packageStartupMessage to learn how to add a message to that gets displayed whenever a user loads the package.

Example Archive Research Packages

Support

A package with the designation "Support" may not have a research component, and also may not be intended for a wide, general audience. However, these packages may be critically important to other projects throughout the USGS. Therefore, it is important to follow best-practices in the package development, as well as clearly communicate the intent and level of support for these packages. See ?packageStartupMessage to learn how to add a message to that gets displayed whenever a user loads the package.

The following disclaimer applies to all support packages that do not have an associated peer-reviewed article included in a CITATION file.

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.

Refer to https://www2.usgs.gov/fsp/fsp_disclaimers.asp for more information.

  • An active USGS employee is designated as maintainer. Development and maintenance of support packages should include a team of developers. Maintainers coordinate and lead the development team, but should not be the sole developer.
  • The package is well tested
  • For example, all critical functions should be tested for expected results using the testthat package. The coverage of testing can be measured using the coveralls or codecov services.

  • The package should be tested on a continuous integration platform regularly. A few example continuous integration platform services are Travis CI, and AppVeyor
  • Key functions should have clear documentation and working examples.
  • An official disclaimer is shown on the README, and any vignettes:
  • The package startup message needs to either include the above disclaimer, or link to this page:
  • 
    .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
    
    

Example Support Packages

Orphan

A package with the designation "Orphan" does not have an active USGS employee designated as maintainer. The odds of a package becoming orphaned can be minimized during the package-creation phase by using a team of developers to collaborate, emphasizing clear documentation and high test-coverage. Community efforts to troubleshoot issues and submit bug-fixes are encouraged. Orphan packages should include some communication on both the readme and package startup message that the status is "orphan" and information on whom to contact to volunteer to take over maintainer duties.

The following disclaimer applies to all orphan packages that do not have an associated peer-reviewed article included in a CITATION file.

Training from USGS-sponsored courses should avoid orphan packages until they have designated an active maintainer and have addressed long-term resource commitments.

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.

Refer to https://www2.usgs.gov/fsp/fsp_disclaimers.asp for more information.

Current Orphan Packages

If you are interested in taking over maintainer status for any of the following packages, please email <gs-w_r_admin@usgs.gov>. USGS-R admins will make a strong effort to communicate the status of orphan packages.