Package 'PBSadmb'

Start the PBSadmb GUI for ADMB

Description

Start up the PBSadmb GUI for controlling and running AD Model Builder.

Usage

admb(prefix="", wdf="admbWin.txt", pathfile="ADpaths.txt")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb').
wdf	character – name of the window description file that creates the GUI.
pathfile	character – name of 2-column text file that details the relevant paths for the R variables admbpath, gccpath, and editor.

Details

The pathfile has now replaced the optfile, which no longer exists as an argument. The pathfile identifies valid paths, which are passed to the options manager. Additionally, the user can change whichever path settings are desired through the GUI.

The package still recognizes the file 'ADopts.txt', which has been demoted to a back-up file that will be saved only when the user pushes the Save button on the first tab in the GUI. If ADopts.txt exists and the options file .PBSadmb is not available (i.e. NULL), then ADopts.txt will be used on start up to populate the GUI.

Warning

Do not call your pathfile="ADopts.txt" unless you want to tempt fate.

Note

On UNIX systems, the MinGW compiler and UNIX tools are readily available; therefore, only the admbpath (path to ADMB's home directory) and the path to a text editor are needed.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC
Alex Couture-Beil, Software Engineer, Victoria BC
Anisa Egeli, former MUC student, Nanaimo BC

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-25

See Also

In package PBSadmb:
setADpath, readADopts, readADpaths, makeAD

---

Append Data to Log File

Description

Append summary information or output to a previously created log file.

Usage

appendLog(prefix, lines)
.win.appendLog(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb')
lines	character – data to append to 'prefix'.log)
winName	character – name of GUI window

Value

No explicit value returned. Appends data into a log file 'prefix'.log.

Note

A wrapper function that can be called from a GUI exists as .win.appendLog.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
startLog, editAD

---

Get/Put Objects From/To Temporary Work Environment

Description

These functions are wrappers to the PBSmodelling accessor functions that get/print objects from or put objects into a temporary work environment, in this case .PBSadmbEnv. Working objects include PBSadmb, which acts as a storage object for some of the functions, and .PBSadmb, which controls the options for the user's project.

Usage

atget(...)
atcall(...)
atprint(...)
atput(...)
alisp(...)

Arguments

...

For atget through to atput, the only free argument is: x – name (with or without quotes) of an object to retrieve or store in the temporary environment; cannot be represented by a variable. Fixed arguments: penv = parent.frame(), tenv = .PBSadmbEnv See tget for additional information. For alisp, there is only one fixed argument: pos = .PBSadmbEnv All other arguments are available – see lisp

Details

These accessor functions were developed as a response to the CRAN repository policy statement: “Packages should not modify the global environment (user's workspace).”

Value

Objects are retrieved from or sent to the temporary working environment to/from the place where the function(s) are called. Additionally, atcall invisibly returns the object without transferring, which is useful when the object is a function that the user may wish to call, for example, atcall(myfunc)(), or as arguments in other functions.

Note

Additional wrapper functions to access functions in .PBSadmbEnv are named with the prefix .win (none at the moment).

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Offsite, Vancouver BC
Last modified Rd: 2023-11-10

References

CRAN Repository Policy

See Also

In package PBSmodelling:
tget, and lisp

---

Check ADMB Options for Path Integrity

Description

Check that the options object '.PBSadmb' has all required components and that paths point to actual files on the hard drive.

Usage

checkADopts(opts=getOptions(atcall(.PBSadmb)),
   check=c("admbpath","gccpath","msysbin","editor"), 
   warn=TRUE, popup=FALSE, verify=TRUE)

.win.checkADopts(winName="PBSadmb")
.win.checkADpath(winName="PBSadmb")

Arguments

opts	list – ADMB options values.
check	character – components (directory paths) of .PBSadmb to check.
warn	logical – if TRUE, print the results of the check to the R console.
popup	logical – if TRUE, display program location problems in a popup GUI.
verify	logical – if TRUE, then the ‘Verify’ button in the GUI was pressed. This only affects the message generation ‘All programs found’. Command line call does not depend on GUI.
winName	character – name of GUI window

Value

Boolean value where TRUE indicates all programs were located in the specified directories and FALSE if at least one program cannot be found. The returned Boolean scalar has two attributes:
warn – named list of test results, and
message – named vector of test results.

Note

A wrapper function that can be called from a GUI exists as .win.checkADopts.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
setADpath, readADopts

---

Clean ADMB-Generated Files from Working Directory

Description

Detect files in the working directory with the specified prefix and removes them all, save those with the suffix .tpl, .dat, and .pin.

Usage

cleanAD(prefix)
.cleanUp(prefix, suffix, files)
.cleanUpAgain(winName="cleanWindow")
.cleanWD(files)
.doCleanAD(winName="cleanWindow")
.win.cleanAD(winName="PBSadmb")
.win.findClean(winName="cleanWindow")

Arguments

prefix	character – prefix of the ADMB project (e.g., 'vonb')
suffix	character – vector of suffixes/extensions for files to be removed
files	character – vector of explicit file names for removal
winName	character – name of GUI window

Details

Aside from potential garbage files with the specified 'prefix', other files associated with ADMB are detected. Also files '*.tmp' and '*.bak' are displayed. Calling 'cleanAD' invokes the hidden function '.cleanUp', which creates a GUI menu of the potential garbage files. The user can select whichever files desired for disposal.

Value

Returns nothing. Invokes a GUI menu of potential garbage files.

Note

A wrapper function that can be called from a GUI exists as '.win.cleanAD'.

.cleanUp – Anisa Egeli's PBSmodelling::cleanProj function modified for flexibility.
.cleanWD – clean all potential garbage files; Anisa Egeli's function PBSmodelling::cleanWD.
.doCleanAD – Anisa Egeli's PBSmodelling:::.doClean function modified for file names only.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-25

See Also

In package PBSadmb:
makeAD, runAD, readRep

---

Compile C Code

Description

Compile C++ code in 'prefix'.cpp to create a binary object file 'prefix'.o.

Usage

compAD(prefix, raneff=FALSE, safe=TRUE, dll=FALSE, debug=FALSE, 
   logfile=TRUE, add=TRUE, verbose=TRUE, pathfile=NULL)

.win.compAD(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb').
raneff	logical – if TRUE, use the random effects model, otherwise use the normal model (currently does not influence the compile stage, but the argument is preserved here for future development).
safe	logical – if TRUE, use safe mode with bounds checking on all array objects, otherwise use optimized mode for fastest execution.
dll	logical – if TRUE, create dll (rather than executable)
debug	logical – if TRUE, compile with debug symbols
logfile	logical – if TRUE, create a log file of the messages from the shell call.
add	logical – if TRUE, append shell call messages to an exsiting log file.
verbose	logical – if TRUE, report the shell call an its messages to the R console.
pathfile	character – name of 2-column text file that details the relevant paths for the R variables admbpath, gccpath, and editor.
winName	character – name of GUI window

Details

This function uses the C++ comiler declared in .PBSadmb. If logfile=TRUE, any errors will appear in 'prefix'.log. If verbose=TRUE, they will appear in the R console.

Value

Invisibly returns the shell call and its messages.

Note

A wrapper function that can be called from a GUI exists as .win.compAD.

The optional pathfile is offered for use in command (non-GUI) functions. Users can easily create this file in a text editor. Note that on UNIX systems, only the admbpath (actually the path to ADMB's home directory) and text editor are used because the MinGW compiler (gccpath) and UNIX tools are already recognised.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-23

See Also

In package PBSadmb:
convAD, linkAD, makeAD, readADpaths

---

Convert TPL Code to CPP Code

Description

Convert code in 'prefix'.tpl to C++ code in 'prefix'.cpp.

Usage

convAD(prefix, raneff=FALSE, safe=TRUE, dll=FALSE, debug=FALSE, 
   logfile=TRUE, add=TRUE, verbose=TRUE, pathfile=NULL)

.win.convAD(winName="PBSadmb")
.win.checkPrefix(winName="PBSadmb")
.win.findTPL(suffix=".tpl",winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb').
raneff	logical – if TRUE, use the random effects model executable tpl2rem.exe, otherwise use the normal model executable tpl2cpp.exe
safe	logical – if TRUE, use safe mode with bounds checking on all array objects, otherwise use optimized mode for fastest execution.
dll	logical – if TRUE, create dll (rather than executable)
debug	logical – if TRUE, compile with debug symbols
logfile	logical – if TRUE, create a log file of the messages from the shell call.
add	logical – if TRUE, append shell call messages to an exsiting log file.
verbose	logical – if TRUE, report the shell call an its messages to the R console.
pathfile	character – name of 2-column text file that details the relevant paths for the R variables admbpath, gccpath, and editor.
winName	character – name of GUI window
suffix	character – suffix of an ADMB project file (e.g., '.tpl')

Details

Invokes the ADMB command tpl2cpp.exe or tpl2rem.exe, if raneff is FALSE or TRUE respectively. If logfile=TRUE, any errors will appear in 'prefix'.log. If verbose=TRUE, they will appear in R console.

Value

Invisibly returns the shell call and its messages.

Note

A wrapper function that can be called from a GUI exists as .win.convAD.

The optional pathfile is offered for use in command (non-GUI) functions. Users can easily create this file in a text editor. Note that on UNIX systems, only the admbpath (actually the path to ADMB's home directory) and text editor are used because the MinGW compiler (gccpath) and UNIX tools are already recognised.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-23

See Also

In package PBSadmb:
compAD, linkAD, makeAD, readADpaths

---

Convert Text Files to Default OS Format

Description

Convert text files to the default format of the operating system.

Usage

convOS(inam, onam = inam, path = getwd() )

Arguments

inam	character – vector of names specifying files to be converted to the format of the operating system
onam	character – vector of name specifying the output files (the default overwrites the input file)
path	character – specifying the path where the input files are located (defaults to current working directory)

Value

Text file(s) formatted in accordance with standards of the operating system.

Note

This function essentially executes a readLines command followed by a call to writeLines.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
copyFiles, .addQuotes

---

Copy System Files

Description

Copy files with specified prefixes and suffixes from one location to another.

Usage

copyFiles(prefix, suffix=NULL, srcdir=getwd(), dstdir=getwd(), ask=TRUE)

Arguments

prefix	character – scalar/vector of potential file prefixes.
suffix	character – scalar/vector of potential file suffixes.
srcdir	character – source directory from which to copy files.
dstdir	character – destination directory to copy files to.
ask	logical – if TRUE, popup boxes will prompt the user for every instance that a file will be overwritten.

Details

This function uses R's list.files and file.copy functions. The pattern recognition tends not to work when given the wildcard character *; however, the user may use this character, and the code will interpret it.

Value

Invisibly returns a Boolean vector with names of files that have been copied or not.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
editAD

---

Miscellaneous Dot Functions

Description

An assortment of dot functions to facilitate running PBSadmb.

Usage

.addQuotes(str)
.asIs(x)
.callSys(..., wait=TRUE)
.changeWD(wd)
.changeWDEnter()
.chooseCols(winName="PBSadmb")
.getDirName(path)
.load.prefix.droplist()
.normPath(path, winslash="\\", mustWork=FALSE)
.version(x)

Arguments

str	character – string to which quotation marks are added
x	numeric|character – number for '.asIs'; string for '.version'
...	character – system command and options for 'shell'|'system'
wait	logical – if TRUE, wait until the system command has been executed
wd	character – working directory
winName	character – name of a GUI window
path	character – path on the computing machine
winslash	character – delimiters to use between folders|directories for pathways
mustWork	logical – if TRUE, then pathway must be valid

Details

Small utility functions that were demoted to a hidden status before CRAN required their documentation.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-23

See Also

In package PBSadmb:
admb
In package PBSmodelling:
getWinAct, getWinVal, tget

---

PBSadmb Environment

Description

An environment set aside for PBSadmb.

Usage

.PBSadmbEnv

Format

A new environment with a .GlobalEnv parent.

Details

The environment is created in 'zzz.r' and is used by PBSadmb functions 'alisp', 'atget', 'atput', 'atprint', and 'atcall'.

Source

Generated by a call to the base function new.env().

See Also

In PBSadmb:
alisp, atget
In PBSmodelling:
lisp, tget

---

Edit ADMB Files

Description

Edit files associated with specified prefix and suffixes.

Usage

editAD(prefix, suffix=c(".tpl",".cpp",".log"))
editADfile(fname)
.win.editAD(winName="PBSadmb")
.win.editPLT()

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb')
suffix	character – scalar/vector specifying one or more suffixes
fname	character – name of file in current working directory (or elsewhere if path delimited by / or \)
winName	character – name of GUI window

Value

Invisibly returns Boolean vector with elements TRUE if files exist, FALSE if they do not.

Note

A wrapper function that can be called from a GUI exists as .win.editAD.

This function explicitly uses the editor chosen for PBSadmb. PBSmodelling has another function openFile that uses Windows file associations or an application specified with setPBSext.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
setADpath, copyFiles

---

Link Object Files to Make an Executable

Description

Links the binary object file 'prefix'.o to the ADMB libraries and produces the executable file 'prefix'.exe.

Usage

linkAD(prefix, raneff=FALSE, safe=TRUE, dll=FALSE, debug=FALSE, 
   logfile=TRUE, add=TRUE, verbose=TRUE, pathfile=NULL)

.win.linkAD(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb').
raneff	logical – if TRUE, use the random effects model, otherwise use the normal model
safe	logical – if TRUE, use safe mode with bounds checking on all array objects, otherwise use optimized mode for fastest execution.
dll	logical – if TRUE, create dll (rather than executable)
debug	logical – if TRUE, compile with debug symbols
logfile	logical – if TRUE, create a log file of the messages from the shell call.
add	logical – if TRUE, append shell call messages to an exsiting log file.
verbose	logical – if TRUE, report the shell call an its messages to the R console.
pathfile	character – name of 2-column text file that details the relevant paths for the R variables admbpath, gccpath, and editor.
winName	character – name of GUI window

Details

This function uses the C++ comiler declared in .PBSadmb. If logfile=TRUE, any errors will appear in 'prefix'.log. If verbose=TRUE, they will appear in the R console.

Value

Invisibly returns the shell call and its messages.

Note

A wrapper function that can be called from a GUI exists as .win.linkAD.

The optional pathfile is offered for use in command (non-GUI) functions. Users can easily create this file in a text editor. Note that on UNIX systems, only the admbpath (actually the path to ADMB's home directory) and text editor are used because the MinGW compiler (gccpath) and UNIX tools are already recognised.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-23

See Also

In package PBSadmb:
convAD, compAD, makeAD, readADpaths

---

Make an Executable Binary File from a C File

Description

Essentially a wrapper function that calls in sequence: convAD, compAD, and linkAD.

Usage

makeAD(prefix, raneff=FALSE, safe=TRUE, dll=FALSE, debug=FALSE, 
   logfile=TRUE, add=TRUE, verbose=TRUE, pathfile=NULL)

.win.makeAD(winName="PBSadmb")
.setPath(pathfile)

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb').
raneff	logical – if TRUE, use the random effects model, otherwise use the normal model
safe	logical – if TRUE, use safe mode with bounds checking on all array objects, otherwise use optimized mode for fastest execution.
dll	logical – if TRUE, create dll (rather than executable)
debug	logical – if TRUE, compile with debug symbols
logfile	logical – if TRUE, create a log file of the messages from the shell call.
add	logical – if TRUE, append shell call messages to an exsiting log file.
verbose	logical – if TRUE, report the shell call an its messages to the R console.
pathfile	character – name of 2-column text file that details the relevant paths for the R variables admbpath, gccpath, and editor.
winName	character – name of GUI window

Details

This function uses the C++ comiler declared in .PBSadmb. If logfile=TRUE, any errors will appear in 'prefix'.log. If verbose=TRUE, they will appear in the R console.

Value

Returns nothing. The three functions called by makeAD each return the shell call and its messages.

Note

A wrapper function that can be called from a GUI exists as .win.makeAD.

Internally to makeAD, convAD, compAD, and linkAD, .setPath(pathfile) sets the temporary environment path to run ADMB.

The optional pathfile is offered for use in command (non-GUI) functions. Users can easily create this file in a text editor. Note that on UNIX systems, only the admbpath (actually the path to ADMB's home directory) and text editor are used because the MinGW compiler (gccpath) and UNIX tools are already recognised.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
convAD, compAD, linkAD, runAD, readADpaths

---

PBS ADMB Package

Description

The R package PBSadmb gives complete R support to the external program AD Model Builder, released into the public domain in 2009. The program offers users a remarkably efficient tool for estimating parameters and their uncertainty, based on complex nonlinear statistical models.

In a standard ADMB installation, users would interact with the program via a DOS command shell (in Windows) or a bash shell (in Linux or Mac OS X). The package PBSadmb makes it possible to interact entirely from an R console, as a common interface for all operating systems. A single R script can encapsulate commands to ADMB, as well as all analyses that follow. The package includes protocols for writing code to make the integration between R and ADMB almost seamless.

PBSadmb also provides a Graphical User Interface (GUI) that facilitates the steps required for a complete ADMB analysis. Both new and experienced users can use the GUI for tutorial and educational purposes.

You can obtain PBSadmb from the Comprehensive R Archive Network (CRAN). Always use the current version of PBSadmb with the most recent version of PBSmodelling, another package available from CRAN.

PBSadmb represents just one of a series of R packages developed at the Pacific Biological Station (PBS) in Nanaimo, British Columbia. A more advanced version of PBSadmb might be available on GitHub under PBS Software in the repository pbs-admb. Regardless, a user can install the GitHub version using:

     devtools::install_github("pbs-software/pbs-admb/PBSadmb")

Note: not every revision has been checked for CRAN worthiness.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC
Alex Couture-Beil, Software Engineer, Victoria BC

Maintainer:
Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-25

---

Plot Results of MCMC Simulation

Description

Plot results of an ADMB MCMC simulation using various plot methods.

Usage

plotMC(prefix, act="pairs", pthin=1, useCols=NULL)
.win.plotMC(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb')
act	character – scalar: action describing plot type (current choices: "pairs", "eggs", "acf", "trace", and "dens")
pthin	numeric – scalar indicating interval at which to collect records from the .mc.dat file for plotting
useCols	logical – vector indicating which columns of .mc.dat to plot
winName	character – name of GUI window

Note

A wrapper function that can be called from a GUI exists as .win.plotMC. Use the PBSadmb GUI to explore these plots easily.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
runMC, showADargs

---

Read/Write ADMB Options List From/To File

Description

Read ADMB options list into memory from a file.
Write ADMB options list from memory into a file.

Usage

readADopts(optfile="ADopts.txt")
writeADopts(optfile="ADopts.txt")
.initOptions()

Arguments

optfile

character – name of an ASCII text file containing ADMB options information

Details

Create a PBSoptions class object called .PBSadmb (stored in the package's working environment PBSadmbEnv) and read in ADMB options from an ASCII text file using a load function that ultimately calls PBSmodelling::readList.

Writes the global ADMB options list to a file using the function PBSmodelling::saveOptions.

Dot function '.initOptions' basically calls 'readADopts' if it's the first time (i.e., no options are set in the object '.PBSadmb' in the environment '.PBSadmbEnv').

Value

readADopts – no values returned; reads the ADMB options into the list object '.PBSadmb'.
writeADopts – returns opts invisibly; writes the options list object to an ASCII file.

Author(s)

Alex Couture-Beil, Software Engineer, Victoria BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
atget, readADpaths, setADpath
In package PBSmodelling:
getOptions, loadOptions

---

Read ADMB Paths From a Text File

Description

Read or save ADMB paths (admbpath, gccpath, msysbin, editor) from or to a simple, 2-column text file where the first column gives the R variable name and the second column specifies the path (enclosed by double quotation marks “”).

Usage

readADpaths(pathfile)
saveADpaths(pathfile)
.win.readADpaths(winName="PBSadmb")
.win.saveADpaths(winName="PBSadmb")

Arguments

pathfile	string name of 2-column text file that details the relevant paths for the R variables admbpath, gccpath, msysbin, and editor.
winName	character – name of GUI window

Details

The simplest way to pass valid paths to the options manager in PBSadmb is to supply a text file in the working directory. This file can be constructed easily using any text editor. An example might look like:

admbpath "C:/Apps/admb_13.2"
gccpath  "C:/Apps/R/Rtools44/x86_64-w64-mingw32.static.posix"
msysbin  "C:/Apps/R/Rtools44/usr/bin"
editor   "C:/Apps/UltraEdit/Uedit32.exe"

Note

On UNIX systems the MinGW compiler and UNIX tools are readily available; therefore, only the admbpath (path to ADMB's home directory) and the path to a text editor are needed.

The user can supply any number of paths in a pathfile, which are passed to the options manager; however, only the above four paths are used at present.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
readADopts, convAD, compAD, linkAD, makeAD

---

Read an ADMB Report into R Memory

Description

Import ADMB-generated report files into R's memory using the names of the report files to name the R-objects.

Usage

readRep(prefix, suffix=c(".cor",".rep",".std",".mc.dat"), global=FALSE)

.win.readRep(winName="PBSadmb")
.win.viewRep(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb')
suffix	character – scalar/vector specifying one or more suffixes
global	logical – if TRUE, save the imported reports as objects to global environment using the same names as the report files
winName	character – name of GUI window

Details

If the report object is one of c(".cor", ".std", ".mc.dat"), the report object is a data frame, otherwise it is a string vector. Multiple report objects are returned as a list of objects. A single report object is returned as the object itself.

This function attempts to detect the file format from a number of possibilities. For example, if the file has the special format recognized by PBSmodelling, then the function returns a list with named components. The example vonb included with this package shows how to write the template to get consistent variable names between ADMB and R. See the User's Guide for complete details.

Value

Invisibly returns the list of report objects. If only one report is imported, a single report object is returned.

Note

A wrapper function that can be called from a GUI exists as .win.readRep.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
editAD

---

Run an Executable Binary File

Description

Run the executable binary file 'prefix'.exe that was created by makeAD.

Usage

runAD(prefix, argvec="", logfile=TRUE, add=TRUE, verbose=TRUE)

.win.runAD(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb').
argvec	character – scalar/vector of arguments appropriate for the executable 'prefix'.exe.
logfile	logical – if TRUE, create a log file of the messages from the shell call.
add	logical – if TRUE, append shell call messages to an exsiting log file.
verbose	logical – if TRUE, report the shell call an its messages to the R console.
winName	character – name of GUI window

Details

This function typically reads the two files 'prefix'.dat and 'prefix'.pin, although in same cases one or both of these files may not be necessary.

If logfile=TRUE, output (including error messages, if any) will appear in 'prefix'.log. If verbose=TRUE, it will appear in the R console.

Value

Invisibly returns the results of the shell call.

Note

A wrapper function that can be called from a GUI exists as .win.runAD.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-23

See Also

In package PBSadmb:
runMC, makeAD, cleanAD

---

Run an Executable Binary File in MCMC Mode

Description

Run the executable binary file 'prefix'.exe, created by makeAD, to generate MCMC simulations.

Usage

runMC(prefix, nsims=2000, nthin=20, outsuff=".mc.dat",
      logfile=FALSE, add=TRUE, verbose=TRUE)

.win.runMC(winName="PBSadmb")
.win.run(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb').
nsims	numeric – scalar indicating number of MCMC simulations to perform.
nthin	numeric – scalar indicating the sampling rate or thinning of the nsims MCMC simulations to report.
outsuff	character – name suffix of the MCMC output data file.
logfile	logical – if TRUE, create a log file of the messages from the shell call.
add	logical – if TRUE, append shell call messages to an exsiting log file.
verbose	logical – if TRUE, report the shell call an its messages to the R console.
winName	character – name of GUI window

Details

This function runs 'prefix'.exe twice, first with the arguments -mcmc 'nsims' -mcsave 'nthin' and second with the argument -mceval. By default, output goes to the file 'prefix'.mc.dat, although a user can specify a different output suffix.

To see this function in action, use the PBSadmb GUI with the example vonb or simpleMC.

Value

Invisibly returns the results of the shell call.

Note

A wrapper function that can be called from a GUI exists as .win.runMC.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-23

See Also

In package PBSadmb:
runAD, makeAD, cleanAD

---

Create ADMB Options List

Description

Creates an options list object detailing the pathways to the ADMB home directory, the GCC home directory, the MSYS (Unix utilities) bin directoy, and the user's preferred text editor. Also keeps track of software versions for ADMB and GCC.

Usage

setADpath(admbpath, gccpath, msysbin, editor)
setADver(admbver, gccver)
.win.setADver(winName="PBSadmb")

Arguments

admbpath	character – explicit path to the user's ADMB home directory
gccpath	character – explicit path to the user's GCC home directory
msysbin	character – explicit path to the user's MSYS bin directory (binary executables and libraries)
editor	character – explicit path and program to use for editing text
admbver	character – version number of ADMB software
gccver	character – version number of g++ software
winName	character – name of GUI window

Value

Creates a global, hidden list object called '.PBSadmb', located in the temporary environment .PBSadmbEnv. Use the functions atget, atput, atcall, and atprint to get, put, call, and print the object .PBSadmb. The function alisp lists all the objects in the .PBSadmbEnv environment.

Note

These functions replace makeADopts (deprecated). The old control file called ADopts.txt is retained as a backup file system, which is accessed on R session start-up and first call to the function admb() to initialize the contents of the options manager .PBSadmb and the GUI. However, if a path file (e.g., ADpaths.txt) exists, the paths in this file will override those taken from ADopts.txt.

Additionally, the ‘Verify’ button always consults the admb version file (if it exists) and the g++ executable to collect version information. If not available, version information is set to an empty string.

Author(s)

Alex Couture-Beil, Software Engineer, Victoria BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
readADopts, readADpaths

---

Set Up Paths for PBSadmb

Description

Set up path information by reading from a pathfile (default = ADpaths.txt) and checking that certain executable files exist.

Usage

setupAD(pathfile)

Arguments

pathfile

character – name of 2-column text file that details the relevant paths for the R variables admbpath, gccpath, and editor.

Details

This program is useful primarily for console-based function calls. It sets up the background options for PBSadmb functions (convAD, compAD, linkAD) by reading paths from a file and checking to make sure that they are valid (i.e., contain certain exectuable files like tpl2cpp and g++). The options are store in a PBSoptions class objects called .PBSadmb in the temporary environment .PBSadmbEnv.

Note

To access the options manager in the temporary working environment, use the PBSadmb accessor functions (atget, atput, atcall, atprint). For eample:

atprint(.PBSadmb)

On UNIX systems the MinGW compiler and UNIX tools are readily available; therefore, only the admbpath (path to ADMB's home directory) and the path to a text editor are needed.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-23

See Also

In package PBSadmb:
readADpaths, checkADopts, makeAD

---

Show All Arguments for ADMB Executable

Description

Show all arguments available for an ADMB executable in the default text editor.

Usage

showADargs(prefix, ed=TRUE)
.win.showADargs(winName="PBSadmb")
.win.showGUIargs(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., "vonb")
ed	logical – if TRUE, write the ADMB arguments to a file and view them with the text editor, else display the arguments on the R console
winName	character – name of GUI window

Value

Invisibly returns the argument list.

Note

A wrapper function that can be called from a GUI exists as .win.showADargs.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
editADfile, runAD

---

Start a Log File

Description

Start a log file by removing any previous version and appending header information.

Usage

startLog(prefix)
.win.startLog(winName="PBSadmb")

Arguments

prefix	character – name prefix of the ADMB project (e.g., 'vonb')
winName	character – name of GUI window

Value

No explicit value returned. Writes header lines into a log file 'prefix'.log.

Note

A wrapper function that can be called from a GUI exists as .win.startLog.

Author(s)

Jon T. Schnute, Scientist Emeritus, Nanaimo BC

Maintainer: Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-24

See Also

In package PBSadmb:
appendLog, editAD

---

Suggest Path to Specified Program

Description

Suggest a directory path from the system PATH where a program specified by the user might be located.

Usage

suggestPath(progs, ipath = NULL, file_ext = NULL)
.win.suggestPath(winName="PBSadmb")

Arguments

progs	character – vector of program names without the extension (assumes '.exe' in Windows); Unix programs do not have extensions
ipath	character – specified by the user as the initial path (directory) to check before checking all other directories on the PATH
file_ext	character – user can specify an alternative extension if the program does not end in '.exe'
winName	character – name of GUI window

Details

Determine whether the specified programs can be located on the user's system.

A wrapper function called .win.suggestPath is used by the PBSadmb GUI to suggest paths for the ADMB home, the Windows MinGW home, and an editor.

Value

Returns a logical vector where each element corresponds to a program searched. If the element is TRUE, then the program was found on the path, which is supplied as the name of the vector element. If the element is FALSE, the program may exist on the user's system, but is not in any of the directories specified by the PATH environment of the system.

The returned vector has a list attribute where each item in the list corresponds to each element in the vector, and shows the results of the search for each of the directories.

Note

A wrapper function '.win.suggestPath' can be called from a GUI.

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-04-25

See Also

In package PBSadmb:
setADpath

---