Package 'icesTAF'

Functions to Support the ICES Transparent Assessment Framework

Description

Functions to support the ICES Transparent Assessment Framework, to organize data, methods, and results used in ICES assessments.

Details

Initial TAF steps:

draft.data.script	create boot script
taf.roxygenise	create DATA.bib entry from tags

Author(s)

Colin Millar and Arni Magnusson.

References

ICES Transparent Assessment Framework: https://taf.ices.dk.

To explore example TAF stock assessments, see the introductory video and tutorial.

The TAF Wiki provides additional help resources.

---

Import a boot data script from ICES datasets repo

Description

Download an ‘R’ file from the ICES datasets repo to fetch data including adding metadata via roxygen2 fields to the top of the file.

Usage

add.data.script(name, install.deps = TRUE, commit = FALSE)

Arguments

name	the name of the dataset.
install.deps	install packages used in the script if not already installed.
commit	should the boot script be added and committed to the analysis.

Examples

## Not run: 

# Create boot folder
mkdir(taf.boot.path())

# Create boot script, boot/mydata.R
add.data.script(name = "vms")

# Create metadata, boot/DATA.bib
taf.roxygenise(files = "vms.R")

# Run boot script, creating boot/data/vms/...
taf.boot()

## End(Not run)

---

Print a directory tree

Description

Print the directory tree and file contents in a pretty way

Usage

dir.tree(path = ".")

Arguments

path	the directory for which the listing is to be shown

See Also

list.files

Examples

## Not run: 

library(icesTAF)

# Download a TAF analysis
dir.tree()

## End(Not run)

---

Download a TAF analysis

Description

Download the code for a TAF analysis from GitHub.

Usage

download.analysis(repo, dir = tempdir())

Arguments

repo	The full name of the GitHub repository, e.g. "ices-taf/2019_san.sa.6".
dir	the directory to place the TAF project

See Also

run.analysis

Examples

## Not run: 

library(icesTAF)

# Download a TAF analysis
run_dir <- download.analysis("ices-taf/2019_san.sa.6", dir = ".")

# run the analysis
run.analysis(run_dir)

## End(Not run)

---

Draft or create a boot data script

Description

Create an ‘R’ file to fetch data including adding metadata via roxygen2 fields to the top of the file.

Usage

draft.data.script(name, title, description, format, originator, year, period,
  access, content)

Arguments

name	the name of the dataset and the file name that will be created.
title	description of the data, including survey names or the like.
description	a more involved description if required.
format	the format of the data produced, e.g. "csv"
originator	who prepared the data, e.g. a working group acronym.
year	year of the analysis when the data were used. The default is the current year.
period	a numeric vector of the form c(1990, 2000), indicating the first and last year that the data cover. Alternatively, a single number if the data cover only one year.
access	data access code: "OSPAR", "Public", or "Restricted".
content	the r code that fetches and saves the data

Examples

## Not run: 

# Create boot folder
mkdir("boot")

# Create boot script, boot/mydata.R
draft.data.script(name="mydata", title="Title", description="Description",
                  format="txt", originator="Me", year="2022",
                  period=c(2000,2020), access="Public",
                  content='write(pi, file="pi.txt")')

# Create metadata, boot/DATA.bib
taf.roxygenise(files="mydata.R")

# Run boot script, creating boot/data/mydata/pi.txt
taf.boot()

## End(Not run)

---

Install packages dependencies of a TAF analysis

Description

Search R scripts for packages that are required and install them.

Usage

install.deps(path = ".", ...)

Arguments

path	a directory or file containing R scripts.
...	arguments passed on to install.packages

See Also

deps

Examples

## Not run: 

library(icesTAF)

# Download a TAF analysis
download("https://github.com/ices-taf/2019_san.sa.6/archive/refs/heads/master.zip")
unzip("master.zip")

# move into analysis folder
setwd("2019_san.sa.6-master")

# list dependencies
deps()

# install dependencies
install.deps()

## End(Not run)

---

Run a TAF analysis

Description

Run the code for a TAF analysis locally.

Usage

run.analysis(dir)

Arguments

dir	the directory where the TAF project is located

See Also

download.analysis

Examples

## Not run: 

library(icesTAF)

# Download a TAF analysis
run_dir <- download.analysis("ices-taf/2019_san.sa.6", dir = ".")

# run the analysis
run.analysis(run_dir)

## End(Not run)

---

TAF Colors

Description

Predefined colors that can be useful in TAF plots.

Usage

taf.green
taf.orange
taf.blue
taf.dark
taf.light

See Also

TAF-package gives an overview of the package.

Examples

taf.green

opar <- par(mfrow=c(3,1))
barplot(5:1, main="Five",
        col=c(taf.green, taf.orange, taf.blue, taf.dark, taf.light))

barplot(6:1, main="Six", col=c(taf.green, taf.orange, taf.blue,
                               taf.dark, taf.light, "white"))

barplot(7:1, main="Seven", col=c("black", taf.dark, taf.light,
                                 taf.green, taf.orange, taf.blue, "white"))
par(opar)

---

Process a TAF repo with the taf roclet

Description

This function builds documentation for a TAF repository using roxygen syntax headers. It depends on the roxygen2 package adding some extra functionality to produce citation entries for data sources

Usage

taf.roxygenise(path = ".", files)

Arguments

path	location of taf repository top level directory. Default is working directory.
files	a vector of file names to parse for documentation.

Examples

## Not run: 

# Create boot folder
mkdir("boot")

# Create boot script, boot/mydata.R
draft.data.script(name="mydata", title="Title", description="Description",
                  format="txt", originator="Me", year="2022",
                  period=c(2000,2020), access="Public",
                  content='write(pi, file="pi.txt")')

# Create metadata, boot/DATA.bib
taf.roxygenise(files="mydata.R")

# Run boot script, creating boot/data/mydata/pi.txt
taf.boot()

## End(Not run)

---

TAF Skeleton

Description

Create initial directories and R scripts for a new TAF analysis using a stock assessment created on stockassessment.org.

Usage

taf.skeleton.sa.org(path = ".", stockname, force = FALSE)

Arguments

path	where to create initial directories and R scripts. The default is the current working directory.
stockname	The short-form name of a stock on stockassessment.org.
force	whether to overwrite existing scripts.

Value

Full path to analysis directory.

See Also

package.skeleton creates an empty template for a new R package.

TAF-package gives an overview of the package.

Examples

## Not run: 
taf.skeleton.sa.org(stockname = "WBCod_2021_cand01")

## End(Not run)

---