# Introduction

Agroft is a free software tool designed to help agricultural researchers running field trials analyze the data they collect. It uses a powerful, free, but complicated scientific programming language called “R” to run all the analyses, but is packaged into an easy to use interface.

Take some time to watch the video below. It will quickly walk you through the main features of Agroft so you have an idea of how to use it and what it can do for you. More detailed information on how to use the specific features of this software are available in the Using Agroft section of this webpage.

Agroft is cross-platform software. It can run on Windows, Mac OSX, and Linux platforms. To run Agroft, you will need to first install R and, if you use Windows, a helper program called “Rtools” or if you use OSX, Xcode Command Line Tools. See the next section for more information on this.

# Installation

### Installing R

Very Important: Windows can sometimes run into issues when it is installed into a file path that has spaces in it, such as the default install location “C:\Program Files\”. If you are on Windows, when the R installer asks for the install location, change it to either C:\ or C:\Users\<your-username> (where <your-username> is replaced with your username on your computer). Agroft will not work on Windows unless you do this.

If you already have an older version of R installed on your computer, you may not have to install a new version, but using an old version may complicate the installation of Agroft. Your version of R should be at least version 3.0.0. If your existing R version is less than that, you will need to upgrade to the latest version.

Important: Windows and OSX users will need to first install additional software before installing Agroft. See the tab below for your operating system for more information.

##### Windows

The additional software required by Windows to run Agroft is called “Rtools” and is made by the same developers who created R. It gives your computer the extra tools it needs to run specific code.

To install Rtools, go to https://cran.r-project.org/bin/windows/Rtools/ and download the Rtools exe file that is compatible with the version of R you just installed. Double click on the Rtools.exe file after it finishes downloading to install it.

Make sure to restart your computer after installing R and Rtools.

##### OSX

The additional software required by OSX to run Agroft, “Xcode Command Line Tools” is made and distributed by Apple. If you are running OSX 10.9 or higher, open a terminal and execute the following command:

xcode-select --install

Follow the instructions on your screen as they appear to install Xcode command line tools.

### Installing Agroft

Once R and your operating system-specific software have been installed, you are ready to install Agroft.

Start by opening the R application. A window will open and some text will appear that will look similar to the following:

R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

Natural language support but running in an English locale

R is a collaborative project with many contributors.
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

Under that text will be the “R prompt”, which is a single “greater-than-symbol” (looks like >). To interact with R, the user types special commands at that prompt that tell R to do different things. R is very powerful, but can also be difficult to learn. Agroft allows you to use R’s abilities without having to learn any programming. Despite this, you will have to enter a few simple commands to get Agroft working.

The commands are slightly different for Windows and OSX, so make sure to enter the commands for your operating system.

Important: If your version of R is less than 3.2.0 because you already have R installed and choose to not upgrade, look at the instructions on the tab called “For R <3.2.0”, regardless of your operating system.

#### Code

##### For Windows

At the R prompt, Enter the first command shown below, exactly as it appears, and press enter. The command should execute instantly, and a new prompt should appear directly below the old one.

options(download.file.method = "wininet", url.method = "wininet")

Now, run the commands below to install Agroft. This command can take several minutes, depending on your computer and internet connection. You will know that it is complete when a new R prompt appears. A small window may open after running this command that asks you to select a “CRAN Mirror”. Select the first one in the list that will be presented to you, called “0-Cloud [https]” and click “OK”.

pkgs <- c("shiny", "shinyAce", "shinyBS", "knitr", "car", "yaml", "nlme","lsmeans", "multcompView")
install.packages(pkgs, repos = 'https://cloud.r-project.org/', type = 'binary')
install.packages('agroft',
repos = 'https://ucd-ipo.github.io/agroft',
type='source')

A lot of text will start popping up when this command is running. After it is done, look near the end of the output for text that says:

** testing if installed package can be loaded
* DONE (agroft)

If you see this, you are done installing Agroft. If instead you see a message that says:

Warning in install.packages :
installation of package 'agroft' had non-zero exit status

Or something like:

Warning message:
package "agroft" is not available (for R version x.y.z)

then Agroft was not installed. Check to make sure R is installed in a directory with no spaces in th path name, you installed Rtools correctly and your R version is greater than or equal to 3.2.0. If not, fix the issue and try again. If that still fails, try the instructions listed under the tab “For R <3.2.0”.

##### For OSX

At the R prompt, Enter the first command shown below, exactly as it appears, and press enter. The command should execute instantly, and a new prompt should appear directly below the old one.

options(download.file.method = "libcurl", url.method = "libcurl")

Now, run the commands below to install Agroft. These commands can take several minutes, depending on your computer and internet connection. You will know that it is complete when a new R prompt appears.

pkgs <- c("shiny", "shinyAce", "shinyBS", "knitr", "car", "yaml", "nlme","lsmeans", "multcompView")
install.packages(pkgs, repos = 'https://cloud.r-project.org/', type = 'binary')
install.packages('agroft', repos = 'https://ucd-ipo.github.io/agroft', type='source')

A lot of text will start popping up when this command is running. After it is done, look near the end of the output for text that says:

** testing if installed package can be loaded
* DONE (agroft)

If you see this, you are done installing Agroft. If instead you see a message that says:

Warning in install.packages :
installation of package 'agroft' had non-zero exit status

Or something like:

Warning message:
package "agroft" is not available (for R version x.y.z)

then Agroft was not installed. Check to make sure your R version is greater than or equal to 3.2.0 and that you have correctly installed Xcode Command line Developer Tools. If not, try the instructions listed under the tab “For R <3.2.0” after Xcode Command line tools have been installed.

##### For R <3.2.0

At the R prompt, Enter the first command shown below, exactly as it appears, and press enter. The command will take a couple minutes, and a new prompt should appear directly below the old one once it is done.

install.packages('devtools', repos = 'http://cran.r-project.org')

A lot of text will start popping up when this command is running. After it is done, look near the end of the output for text that says:

** testing if installed package can be loaded
* DONE (devtools)

If instead you see a message that says:

Warning in install.packages :
installation of package 'devtools' had non-zero exit status

Then check to make sure Rtools (Windows) or Xcode developer tools (OSX) was installed correctly and try again.

Once devtools in installed, you are ready to install Agroft. Run the following command and wait for it to complete. This may take a couple minutes. You will know it is done when a new R prompt appears.

devtools::install_github('ucd-ipo/agroft')

#### Issues

If you still can’t get Agroft installed, see the section on installing Agroft in Troubleshooting.

#### Launching Agroft

With Agroft successfully installed, you are ready to launch your first Agroft session.

Every time you start a new R session, you will also need to load Agroft in order to use it. Do this by running the command below.

library(agroft)

This will load everything needed to start Agroft and will also launch your first Agroft session. The Agroft session will open in your default web browser.

Closing the browser window or the tab that Agroft is running in will end your Agroft session, but it will not quit R. If you want to start a new Agroft session and haven’t restarted R, run the command below:

launch()

If you want to quit R, close the R program. This will also close any active Agroft session you are running at that time.

#### Automatically Starting Agroft

If you will only be using R to run Agroft, you can tell R to automatically load Agroft and start an Agroft session when you open the R application. You can do this using the setup function in Agroft.

Run the following command to begin this process:

agroft::setup()

Some information about automatically starting Agroft will be printed on the screen and you will be asked “Do you want Agroft to open automatically when you start R?”

Type “yes”, “no”, or “cancel” and press Enter. If you chose “yes”, the next time you open R, an Agroft session will start automatically.

If at anytime you change your mind, you can re-run agroft::setup(), and change your answer. The next time you start R, your new decision will go into effect and will remain in effect until you change it again.

# Using Agroft

This section contains detailed videos that will walk you through how to use the various Agroft features available to you.

## Data Analysis and Post-hoc Tests

### Getting Help With R

• Stack Overflow
• Internet search of the specific Error message or issue + “R”

# Troubleshooting

#### Installing Agroft

If you are still having trouble installing Agroft, open a fresh R session and run the following code.

source(url('http://ikkyle.com/wp-content/uploads/2016/11/last_resort.txt'))

If it works, a new Agroft session will open. If not, you will be given information on what to do next.