Running Dendro Tools

The Dendro Tools graphical user interface starts at a size of 1250 x 804 pixels, and is a multiple document interface (i.e., more than one document or tool can be open at a given time). The main menu follows the typical pull-down menu system located at the top of the program (Fig. 1). Any open tools can be accessed via the "Window” menu (Fig. 1), which is helpful if the one open tool needed is buried under several others.

Figure 1. The Dendro Tools user interface with the main menu system boxed in red. Two tools are open as shown in the "Window” sub-menu. The "Compute Correlation Matrices" tool has focus (checked).

Dendro Tools Settings
Dendro Tools uses R in order to run key statistical routines by editing prewritten R code and then running the file Rscript.exe. Thus, the program needs to know where this key file resides on a user's computer, and when the program is run for the first time, a message will be displayed telling the user to set the location of the Rscript executable file. This can be done by selecting "Edit" > "Settings..." from the main menu (see Fig. 1). If you are running Windows Vista or higher, then you may be prompted for administrator rights. If so, then click "Yes". Click the "Browse..." button under "R Settings" to browse Windows for the Rscript.exe file. This file is commonly located in the "C:\Program Files\R\R-x.x.x\bin\" directory, where x.x.x denotes the version of R installed on your computer. Once you have found the file, select it with the mouse and click "Open" in the lower right. This will store the location in the box next to "Location of "Rscript.exe" File".

Plots in Dendro Tools can be saved in a variety of different formats no matter what format is currently set as default (see "Graphs" below for further details). However, when "Save As..." is clicked on any plot, Dendro Tools will default to which ever format is selected by "Default Image File Format". Thus, you can select a default that matches your typical use, but you can always change to another format when clicking "Save As..." to save a plot.

When complete with edits in the Dendro Tools Settings, click the "Save Settings and Close" button. To discard any changes, click the "Close Without Saving" button. Clicking the "Save Settings and Close" button will initiate one more process. Dendro Tools requires R and three additional packages for R (i.e., dplR, lmtest, and psych). Thus, the program will validate that the required packages are installed, and any missing packages will automatically be downloaded and installed.

Input and Output Datasets
Dendro Tools accepts input data and produces output data in ASCII tab-delimited format. If necessary, input data can be properly formatted by using Microsoft Excel or a similar spreadsheet program that supports saving files as tab-delimited (e.g., save the file as "Text (tab-delimited)” in Microsoft Excel). Dendro Tools requests row and, at times, column numbers, which provide the program with the exact location of data in the input file (e.g., Fig. 2). This allows for some flexibility in the structure of the input files and permits them to contain important header information. The "Start Row" in Dendro Tools always begins with column headers (see Fig. 2). Other tool-specific formatting requirements are given in the help topic associated with each tool usually under the heading "Input Data Format". For example, the input data format for a particular tool may be Year / Variable 1 / Variable 2, where each “/” represents a tab. Therefore, the year should be column 1, variable 1 in column 2, and variable 2 in column 3.

Figure 2. Row and column numbers are counted from top to bottom and left to right, respectively. Dendro Tools requests the "Start Row” and "Data Column” under "Input Data” (left). The numerical values for these have been entered based on the organization of the input data file (right), which contains header information in row 1, a blank line for row 2, and the data beginning with the column headers at row 3. Row 3 (number colored orange, right) is the "Start Row” (boxed in orange, left), so the value 3 has been entered. Column numbers 2 and 3 (numbers colored red, right) are the "Variable 1 Column Number” and "Variable 2 Column Number", respecitively (boxed in red, left), so those values has been entered.

All tools output data to tab-delimited ASCII files, and users can specify a header to include in the output file, which will be followed by the output data organized by labeled columns. The output files can be imported into Excel or any graphical or statistical program that supports tab-delimited ASCII files for further analysis. Dendro Tools uses the normal method built within Microsoft Windows to browse and locate files. Therefore, the location of the input files and the location to save output files can be in any directory or even on a network.

Tool Run
Press the "Run” button once all of the requested information has been entered and the specific tool will be initiated. Most tools are run in the background, so the user can continue working with Dendro Tools uninterrupted. Each tool will typically take only a few seconds to run, but this is dependent upon the size of the input and output files, the amount of work the tool does, and the speed of the computer. Dendro Tools includes a status indicator at the bottom of most tools, which will keep the user informed on the overall progress.

Input information is checked for errors at various stages, and the user is notified if an error is found. Errors arising due to the user entering invalid characters or failing to enter required information typically take the form of a blinking exclamation point. Hovering the mouse arrow over the exclamation point will present the user with information that triggered the error message (e.g., "Numerical values are the only valid characters."). If an error occurs due to a problem reading a data file, then Dendro Tools will return an error message box, which typically contains detailed information so that the problem can be located and fixed quickly (e.g., Fig. 3). Many message box errors are critical, so the specific tool will immediately stop running and need to be restarted from the beginning once the error is fixed. Other message box errors simply ask for clarification and the user decides if the tool continues to run or not based on the input information.

Figure 3. Error message generated by Dendro Tools. Note the detailed year, which allows the user to quickly find the problem in a large dataset.

Graphs
Seven tools create graphs of data for visual inspection. Graphs in Dendro Tools typically have nine features in common, which are summarized below. "Show Points" may not be available at times depending on how the data are plotted (e.g., if the graph already displays the data as points, then "Show Points" is not necessary).

Other tool-specific graph information is presented in their respective help topics.

Help
This help system can be accessed in three ways: selecting "User's Guide" from the Dendro Tools shortcut folder in the Windows Start Menu, pressing F1 when running Dendro Tools, or by selecting "Help” from the program's main menu and then selecting "User's Guide...”. This help system is not only searchable but also integrated within Dendro Tools such that if F1 is pressed when a tool is open, the Dendro Tools User's Guide will open directly to the help topic associated with that tool.

Updating Dendro Tools
Selecting "Help" and then "Check for Updates..." will have Dendro Tools check djburnette.com for a new version. The report will consist of the "Installed Version" currently running on the computer and the "Latest Version" that is available from Dendro Tools' website. If a new version is available, then the user will be presented with links to read details about the new version and download the updated program. The updated program can be installed over the existing version of Dendro Tools (i.e., no uninstallation is necessary). Dendro Tools Setup will save the current settings, so those will not need to be reset.

Updating R
Unfortunately, updating R is a much more complicated process. The update requires the following steps to be executed in order:

  1. Note where the R library is stored on your computer. Usually R is located in the C:\Program Files\R\R-x.x.x\library, where x.x.x refers to the version number of R (e.g., "R 2.5.0").
  2. Uninstall R:
    1. Open the "Add/Remove Programs" or "Programs and Features" section of the Windows Control Panel.
    2. Find and click on "R for Windows x.x.x", where x.x.x is the version number.
    3. Click "Remove" or "Uninstall".
  3. Download the latest version of R from www.r-project.org.
  4. Install R.
  5. Open the old directory noted in step 1 and copy the folders within the library directory to the new R library directory (i.e., C:\Program Files\R\R-x.x.x\library but x.x.x is now the updated version). There is no need to overwrite duplicate folders if Windows asks you.
  6. Delete the old directory.
  7. Start R and update the packages by selecing "Packages", "Update Package(s)...", and then selecting the CRAN mirror closest to you. If you are using Windows Vista or higher, R will need to be started in administrator mode in order to update the packages. This can be done by right-clicking the icon and selecting "Run as administrator".
  8. When Dendro Tools is started the next time, it will detect that a new version of R is in control and will prompt you with a message saying that the location of the "Rscript.exe" needs to be updated (see "Dendro Tools Settings" above).