How to build R components

Jump down to:

• Find out tool versions
• Build R DSM and MRDS analysis engines
• Build R DSM and MRDS analysis engines from within R
• Create R DSM and MRDS Roxygen documentation
• Run DSM and MRDS examples
• Install source package and build zip via package
• Copy R packages for use in Visual Basic and release
• How to write tests
• How to run tests from within R
• How to run tests from outwith R
• Run MRDS and DSM within R using captured input files
• Capture MCDS and DSM input files from within Distance for Windows
• Reproduce CDS and MCDS plots of detection function and pdf using R
• Reproduce CDS and MCDS qq-plots using R
• Reproduce MCDS plots of detection functions produced with non-factor covariates within using R

Find out tool versions

R:

• Run:

R --version
R version 3.1.0 (2014-04-10) -- "Spring Dance"

Build R DSM and MRDS analysis engines

• Start command prompt:
  • Select Start => All Programs => Accessories => Command Prompt
• Change into R package folder:

chdir %BASE%\Analysis Engines\DSM\Engine\
chdir %BASE%\Analysis Engines\MRDS\Engine\mrds\

• Check package (–no-manual suppresses an attempt to build a PDF of the manual):

R CMD --no-manual check dsm
R CMD --no-manual check mrds

• Check package for CRAN compliance:

R CMD check --as-cran dsm
R CMD check --as-cran mrds

• Install source package and build zip (–build):

R CMD INSTALL --build dsm
R CMD INSTALL --build mrds

• The above installs the package into the R library. To install one elsewhere run e.g.

mkdir local
R CMD INSTALL -l local --build dsm
R CMD INSTALL -l local --build mrds

• The zip files will be named:

dsm_M.N.R.zip
mrds_M.N.R.zip

• Major version number (M), minor version number (N), revision number (R) depend on Version value in DESCRIPTION file e.g.
  • For DSM, Version: 2.2.3
  • For MRDS, Version: 2.1.5

Build R DSM and MRDS analysis engines from within R

• Start R
• Load the devtools library:

library(devtools)

• Check package (–no-manual suppresses an attempt to build a PDF of the manual):

check("dsm", args="--no-manual")
check("mrds", args="--no-manual")

• Install source package:

install("mrds")
install("dsm")

• Build zip:

build("dsm",binary=T)
build("mrds",binary=T)

• The zip files will be named:

dsm_M.N.R.zip
mrds_M.N.R.zip

• Major version number (M), minor version number (N), revision number (R) depend on Version value in DESCRIPTION file e.g.
  • For DSM, Version: 2.2.3
  • For MRDS, Version: 2.1.5

Create R DSM and MRDS Roxygen documentation

• Start R

• Change into the parent of the directory for which documentation is to be created

• Load the devtools library:

library(devtools)

• Load the files into a package environment e.g.

load_all("dsm")
load_all("mrds")

• Document the package e.g.

document("dsm")
document("mrds")

Run DSM and MRDS examples

• Start R

• Change into the parent of the directory for which documentation is to be created

• Load the devtools library:

library(devtools)

• Load the files into a package environment e.g.

load_all("dsm")
load_all("mrds")

• Run the examples e.g.

run_examples("dsm")
run_examples("mrds")

Install source package and build zip via package

Alternatively, one can build a .tar.gz package:

• Build package tar.gz:

R CMD build dsm
R CMD build mrds

• Install source package and build zip (–build) from package:

R CMD INSTALL --build dsm_M.N.R.tar.gz
R CMD INSTALL --build mrds_M.N.R.tar.gz

Copy R packages for use in Visual Basic and release

• Copy files:

copy %BASE%\Analysis Engines\DSM\Engine\dsm_M.N.R.zip %BASE%\Analysis Engines\Shared Stuff\NEngineInterfaceUtilities\RPackages\
copy %BASE%\Analysis Engines\MRDS\Engine\mrds\mrds_M.N.R.zip %BASE%\Analysis Engines\Shared Stuff\NEngineInterfaceUtilities\RPackages\

• The following Visual Basic components depend on finding these files in this folder:
  • %BASE%\Analysis Engines\Shared Stuff\NEngineInterfaceUtilities\Classes\RProcess.cls
  • %BASE%\Analysis Engines\Shared Stuff\NEngineInterfaceUtilities\Classes\InputFileMakerUtils.cls
  • These are bundled in DnnnnNEIUtil.dll

How to write tests

Distance’s R tests are written in testthat. For more information see:

• Testing
• testthat: Get Started with Testing
• Distance tests in dsm\tests and mrds\tests

How to run tests from within R

• Start R
• Load the testthat library:

library(testthat)

• Load your package, e.g.:

library(dsm)

• Change into the package’s folder using setwd.
• To run all the tests in a file do, e.g.:

test_file("tests/testthat/test_input.R")

• To run all the tests in a folder do, e.g.:

test_file("tests/testthat/")

• To run all the tests in a package do, e.g.:

test_package("dsm")

• To display only a ‘.’ for passed tests and ‘E’ for failed tests add a ‘minimal’ argument, e.g.:

test_file("tests/testthat/test_input.R", "minimal")

How to run tests from outwith R

• Within the package’s tests folder, write a testthat.R file with the content:

library(testthat)
library(PACKAGENAME)
test_check("PACKAGENAME")

• From a command prompt, change into the tests folder, e.g.

chdir dsm\tests\

• Run:

R -file testthat.R

Run MRDS and DSM within R using captured input files

Within R GUI:

• Start R GUI
• Cut and paste in.r commands

Within R batch mode:

• Start R command prompt
• Run:

Rcmd.exe BATCH in.r log.r

Capture MCDS and DSM input files from within Distance for Windows

• Select Tools => Preferences…
• Click Analysis tab
• Check Debug mode (create command files but don’t run engine)
• Check Temp folder

If reusing files elsewhere check to ensure that any paths within the files are updated.

Reproduce CDS and MCDS plots of detection function and pdf using R

• Within Distance for Windows, select Analysis - Results => Copy Plot to Clipboard
• Save clipboard contents to a text file e.g. plot.txt
• Run the following within R:

#this reads in the file just created
forplot<-read.table(file="plot.txt", header=T, sep="\t", dec=".")
#note, depending on your language, dec might be "," rather than "."
#this plots the detection function or pdf (if point transects)
plot(forplot$C1, forplot$C2, type="l", ylim=c(0,max(forplot$C4)),
xlab="Distance", ylab="Detection probability")
#Define labels as you wish
#this adds in the data bars
lines(c(0,0), c(forplot$C3[1], forplot$C4[1]))
lines(forplot$C3, forplot$C4)

Reproduce CDS and MCDS qq-plots using R

• Within Distance for Windows, select Analysis - Results => Copy Plot to Clipboard
• Save clipboard contents to a text file e.g. plot.txt
• Run the following within R:

#this reads in the file just created
forplot<-read.table(file="plot.txt", header=T, sep="\t", dec=".")
#note, depending on your language, dec might be "," rather than "."
#this plots the detection function or pdf (if point transects)
plot(forplot$C1, forplot$C2, type="p", ylim=c(0,max(forplot$C4)),
pch = ".", xlab="Empirical distribution function",
ylab="Fitted cumulative distribution function")
#Define labels as you wish
#this adds in the (0,0) (1,1) line
lines(c(0,1), c(0,1))

Reproduce MCDS plots of detection functions produced with non-factor covariates within using R

• Within Distance for Windows, select Analysis - Results => Copy Plot to Clipboard
• Save clipboard contents to a text file e.g. plot.txt
• Run the following within R:

#this reads in the file just created
forplot<-read.table(file="plot.txt", header=T, sep="\t", dec=".")
#note, depending on your language, dec might be "," rather than "."
#this plots the detection function or pdf (if point transects)
plot(forplot$C1, forplot$C2, type="l", ylim=c(0,1),
xlab="Distance", ylab="Detection probability")
#Define labels as you wish
#this adds in other two lines
lines(forplot$C3, forplot$C4, lty=2)
lines(forplot$C5, forplot$C6, lty=3)