C Getting Help

C.1 First Time Working With R?

This section is designed for first-time users of the DLMtool, or users who may not have a lot of experience with R.

You should be able to skip this section if you are familiar with R and RStudio, installing new R packages, and entering R commands into the R console.

To get started with the DLMtool you will need at least two things:

1. A current version of the R software installed on your machine.
2. The latest version of the DLMtool package.

The R Software

The R software can be freely downloaded from the CRAN website and is available for all operating systems. Updated versions of R are released frequently, and it is recommended that you have the latest version installed.

If you are using Windows OS, you can uses the installr package and the updateR() function to update and install the latest version. Alternatively, head to the CRAN website to download the latest version of R.

RStudio

RStudio is a freely available integrated development environment (IDE) for R. It is not essential that you use RStudio, but it can make things a lot easier, especially if you are new to R. This User Guide assumes that you are using RStudio to operate the DLMtool.

It is important to be aware that RStudio and R are two different pieces of software that must be installed separately. We recommend installing the R software before downloading and installing RStudio.

C.2 Installing the DLMtool Package

If this is the first time you are using DLMtool, you will need to install the DLMtool package from CRAN.

Installing DLMtool Using R Console

This can be done by running the command:

install.packages("DLMtool")

A prompt may appear asking you to select a CRAN mirror. It is best to pick the mirror that is the closest geographical distance.

Installing DLMtool Using RStudio

An alternative method to install the DLMtool package is to click the Packages tab in the lower right panel in RStudio, and click Install. Check that Repository (CRAN, CRANextra) is selected in the Install from: drop-down menu, type DLMtool into the packages dialog box, and click Install.

The DLMtool package relies on a number of other R packages, which the installation process will automatically install. The number of packages that are installed, and the time it takes, will depend on what packages you already have installed on your system (and your download speed).

Updating the DLMtool Package

You will only need to install the DLMtool package once. However, the DLMtool package is updated from time to time, and you will need to re-install from CRAN for each new version.

This can be done by using the update.packages command:

update.packages("DLMtool")

Loading the DLMtool Package

Once installed, the DLMtool package can be loaded into R by typing in the command line:

library(DLMtool)

or locating the DLMtool package in the list of packages in RStudio and checking the box.

C.3 A Brief Note on S4 Methods

The core functions of DLMtool are S4 Classes. Many R users may not have worked with S4 methods before.

R has three different object oriented (OO) systems, the most common of which is known as S3. S3 is known as a generic-function OO, and is a casual system with no formal definition of classes. S4 works similar to S3, but is more formal and uses classes with a more rigid definition.

It is not essential to understand the difference between S3 and S4, or why one is preferred over the other, to use the DLMtool. The most important thing that you need to know how to access the information in S4 classes.

If you have work with R in the past, you are probably familiar with using the $ symbol to access elements in a data frame or list. S4 classes contain a named list of slots which are analogous to a standard R list. However, the slots in a S4 class differ in two important ways:

1. The type of content in each slot (e.g., character, numeric, matrix) is determined in the class definition, and cannot be changed. In other words, you are not able to put content of class character into a slot that is expecting information of class numeric. This is what is meant by the S4 system being more strict than S3.
   
2. The slots are accessed with the @ symbol. This is essentially the same as the $ symbol in S3 classes. You will see examples of this throughout the User Guide.

The main thing to note here is that when you see the @ symbol being used, it refers to some particular information (a slot) being accessed from a larger collection of data (the object).

For further information on the S3 and S4 systems see Advanced R.

C.4 Additional Help on the DLMtool

This User Guide aims to explain the workings of the DLMtool, and address the most common questions and issues associated with the package.

Additional help material for the DLMtool package and functions can be obtained in the usual way:

help(DLMtool)

Documentation for each function can be obtained by typing a ? symbol followed by the function name. For example:

?runMSE

Information on the DLMtool classes can be found by first typing class followed by the ? symbol and the class name. For example:

class?Data

You can access this user guide at any time from the R console:

userguide()

C.5 Questions on R-related Problems

Although the User Guide attempts to address the most common issues, undoubtedly there will be times where you have problems with your R code. R has a somewhat annoying habit of returning cryptic error messages, that are sometimes indecipherable, especially to those who are new to the software.

Most coding problems with the R language are the result of a missing parenthesis, an extra or missing comma or quotation mark, or some other minor typo that stops your code from running.

There are a number of resources available on the Internet that are devoted to dealing with questions and problems with R programming. StackOverflow is great place to start searching for answers to your R-related problems.

There is a high chance that in the past someone has posted the exact question that you are dealing with, and one or several kind souls have provided helpful solutions. If not, you can post your own question. But be aware, the StackOverflow community is made up entirely of people who volunteer their time to help others, and they sometimes have little patience for questions that don’t demonstrate a proper search for already posted answers to the problem.