R 📦 to download, cache and read in different versions of the RAM Legacy Stock Assessment Data Base, an online compilation of stock assessment results for commercially exploited marine populations from around the world.
Branch: master
Clone or download
Latest commit a6297a1 Jan 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.Rproj.user update vignette html Jan 23, 2019
R update doc and vignette with v4.4 Jan 23, 2019
docs Merge branch 'master' of https://github.com/kshtzgupta1/ramlegacy Dec 19, 2018
man update vignette html Jan 23, 2019
tests
vignettes
.Rbuildignore
.gitignore fix vignette and hopefully travis run that one crucial download_ramle… Nov 16, 2018
.travis.yml fixed 1 download test & add covr Nov 18, 2018
DESCRIPTION add pckg website Dec 19, 2018
LICENSE
NAMESPACE test build Nov 11, 2018
README.Rmd
README.md
_config.yml
_pkgdown.yml link vignette in README Dec 19, 2018
appveyor.yml add datasets Oct 5, 2018
codecov.yml
codemeta.json
ramlegacy.Rproj

README.md

ramlegacy

Travis Build Status AppVeyor Build Status Coverage status Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.

ramlegacy is an R package that supports caching and reading in different versions of the RAM Legacy Stock Assessment Data Base, an online compilation of stock assessment results for commercially exploited marine populations from around the world. More information about the database can be found here.

What does ramlegacy do?

  • Provides a function download_ramlegacy(), to download all the available versions of the RAM Legacy Stock Assessment Excel Database as RDS objects. This way once a version has been downloaded it doesn't need to be re-downloaded for subsequent analysis.
  • Supports reading in the cached versions of the database through loading the package i.e. calling library(ramlegacy) and also by providing a function load_ramlegacy() to load any specified version.
  • Provides a function ram_dir() to view the path where the downloaded database was saved.

Installation

You can install the development version from GitHub with:

install.packages("devtools")
library(devtools)
install_github("kshtzgupta1/ramlegacy")

To ensure that the vignette is installed along with the package make sure to remove --no-build-vignettes from the build_opts in install_github

Usage

Please see the ramlegacy vignette for more detailed examples and additional package functionality.

Start by loading the package using library.

library(ramlegacy)

When ramlegacy is loaded for the first time after installation of the package calling library(ramlegacy) will prompt the user to download a version of the database using download_ramlegacy(). After downloading a version or multiple versions of the database the subsequent behavior of library(ramlegacy) will depend on which version/versions were downloaded and are present on disk as well as whether library(ramlegacy) is called in an interactive vs non-interactive session. For more details about this behavior please see the ramlegacy vignette.

download_ramlegacy

download_ramlegacy() downloads the specified version of RAM Legacy Stock Assessment Excel Database and then saves it as an RDS object in user’s application data directory as detected by the rappdirs package. This location is also where load_ramlegacy() will look for the downloaded database.

# downloads version 3.0
download_ramlegacy(version = "3.0")

If version is not specified then download_ramlegacy defaults to downloading current latest version (4.3) :

# downloads current latest version 4.3
download_ramlegacy()

To ensure that the user is able to download the data in case www.ramlegacy.org is down, the function also supports downloading all the different versions of the database from a backup location:

# downloads version 1.0 from backup location if www.ramlegacy.org is down
download_ramlegacy(version = "4.3")

load_ramlegacy

After the specified version of the database has been downloaded through download_ramlegacy, in addition to calling library(ramlegacy) to read in the database we can call load_ramlegacy() to do the same thing. That is, calling load_ramlegacy makes all the dataframes present in the database become available in the user's global environment. Note that load_ramlegacy() does not support vectorization and can only load and read in one version at a time. If version is not specified then load_ramlegacy defaults to loading the latest version (currently 4.3) :

# load version 3.0
load_ramlegacy(version = "3.0")

# loads the latest version (currently 4.3)
load_ramlegacy()

ram_dir

To view the exact path where a certain version of the database was downloaded and cached by download_ramlegacy you can run ram_dir(vers = 'version'), specifying the version number inside the function call:

# downloads version 2.5
download_ramlegacy(version = "2.5")

# view the location where version 2.5 of the database was downloaded and cached
ram_dir(vers = "2.5")

Similar Projects

  1. ramlegacy Sean Anderson has a namesake package that appears to be a stalled project on GitHub (last updated 9 months ago). However, unlike this package which supports downloading and reading in the Excel version of the database, Sean Anderson's project downloads the Microsoft Access version and converts it to a local sqlite3 database.

  2. RAMlegacyr RAMlegacyr is an older package last updated in 2015. Similar to Sean Anderson's project, the package seems to be an R interface for the Microsoft Access version of the RAM Legacy Stock Assessment Database and provides a set of functions using RPostgreSQL to connect to the database.

Citation

Use of the RAM Legacy Stock Assessment Database is subject to a Fair Use Policy.

Please cite the RAM Legacy Stock Assessment Database as follows:

Ricard, D., Minto, C., Jensen, O.P. and Baum, J.K. (2013) Evaluating the knowledge base and status of commercially exploited marine species with the RAM Legacy Stock Assessment Database. Fish and Fisheries 13 (4) 380-398. DOI: 10.1111/j.1467-2979.2011.00435.x