From the database’s website:
The RAM Legacy Stock Assessment Database is a compilation of stock assessment results for commercially exploited marine populations from around the world. It is inspired by Dr. Ransom A. Myers’ original stock-recruitment database, which is no longer being updated."
As of April 2019, the available versions are 1.0, 2.0, 2.5, 3.0, 4.3, 4.40, 4.41, 4.44.
The latest versions of the database (4.44, 4.41, 4.40) are available at Zenodo. This is where
download_ramlegacy downloads the database from.
The older versions of the database (4.3, 3.0, 2.5, 2.0, 1.0) are available in Excel (Microsoft Excel Open XML Format Spreadsheet) format at this github repo.
The goal of
ramlegacy is to cache a specified version(s) of the RAM Legacy Stock Assessment Excel Database and this way save time and effort spent in re-downloading different versions of the database as part of any future analysis involving the data. The package also supports reading in any specified dataframe(s) of the database through a function called
load_ramlegacy(). The user can always view the location to which the database is cached and read from by running
ram_dir() and specifying its version argument. This vignette will outline a few more details about these functions and the package that will hopefully make
ramlegacy easy to use.
You can install the development version from github with the
install_github function available in
To ensure that the vignette is installed along with the package make sure to remove
--no-build-vignettes from the
You can download any available version of the RAM Legacy Stock Assessment Excel Database (“1.0”,“2.0”, “2.5”, “3.0”, “4.3”, “4.40”, “4.41”, and “4.44”) through
# download version 1.0 download_ramlegacy(version = "1.0") # download version 2.0 download_ramlegacy(version = "2.0") # download version 2.5 download_ramlegacy(version = "2.5") # download version 3.0 download_ramlegacy(version = "3.0") # download version 4.3 download_ramlegacy(version = "4.3") # download version 4.44 download_ramlegacy(version "4.44")
If version is not specified then
download_ramlegacy will default to downloading the latest version of the database:
# downloads latest version (currently 4.44) download_ramlegacy()
If you want to download multiple versions please download them one at a time as passing them all at once will throw an error.
To enable caching behavior, before downloading the specified version
download_ramlegacy checks whether that version has already been downloaded. If it is then
download_ramlegacy gives the user the option to either download again and overwrite the existing version or not download and just exit the function. This behavior is modified if
overwrite, a function argument to
download_ramlegacy, is set to true. Then even if the version has already been downloaded calling
download_ramlegacy will download it again overwriting the already present version. After downloading the database download_ramlegacy caches it by converting it to an RDS object which can then be read in through calling
download_ramlegacy also has three other arguments:
quiet. By default
ram_path has been set to a location provided by the rappdirs package and can be viewed by calling
ram_dir(vers = "version"). Although this is not the recommended approach download_ramlegacy supports downloading to a user-specified path.
ram_url is fixed to the zenodo URL of the database. Please do not pass in any other url to ram_url. By default,
download_ramlegacy after it is called keeps the user updated of the download progress through status messages. Setting
quiet to TRUE enables the user to suppress all status messages.
This section illustrates the contents and file structure of the directory to which the database is saved once you call
If you have downloaded multiple versions through
download_ramlegacy() the contents of ramlegacy directory (the path to this directory can be viewed by calling
ram_dir()) on your local computer will look something like this with each version getting its own subdirectory within the directory:
For older versions (1.0, 2.0, 2.5, 3.0, 4.3) the contents of the version subdirectory look like this:
For these older versions, the version subdirectory would contain the excel database and serialized database saved under the names
RLSADB v <version no> (assessment data only).xlsx and
v <version number> .rds respectively.
For newer versions (4.40, 4.41, 4.44) along with the excel file of the database file other documents like stock summary files are also downloaded:
The actual excel file of the database and the serialized rds database will be present as
RLSADB v <version no> (assessment data only).xlsx and
v <version no> .rds respectively inside the
DB Files With Assessment Data folder.
For a description of the dataframes present in the database as well as information on the stock summary files present in the database please see this page.
load_ramlegacy can be used to obtain a list of particular dataframes and passed in to the
tables argument. To get a list of all the dataframes within a specific version of the database set
tables = NULL. Make sure that the version you want to load was downloaded and is already present locally at the path you specify using
load_ramlegacy will throw an error.
# returns a list containing area and bioparams tables from version 4.44 database load_ramlegacy(version = "4.44", tables = c("area", "bioparams"))
In case in you want to load multiple versions please load them one at a time as passing them all at once will throw an error. Similar, to
load_ramlegacy has a
ram_path argument which is set to local directory where the specified version of the RAM Legacy Stock Excel Assessment Database was downloaded. You can view that path through
ram_dir(vers = "version"). Although this is not the recommended approach load_ramlegacy supports reading in the database’s dataframes from a user-specified path provided that the database is present at the specified path as an rds file.
To see the path of the directory where the specified version of database was downloaded on the user’s computer, the user can call
ram_dir. Note that this is also the location from which
load_ramlegacy reads in the database.
For example, to see where version 4.3 of the database was downloaded you can call:
# view the path where version 4.3 of the database was cached ram_dir(vers = "4.3")