Guide for Running

AgMIP Climate Scenario

Generation Tools with R
in Windows

Version 2.0
 Version 2.0
Updated July 1st, 2013

Guide for Running AgMIP Climate

Scenario Generation Tools with R
in Windows

This guide explains how to create climate series and climate change scenarios by using the
AgMIP Climate team’s methodology as outlined in the AgMIP Guide for Regional Integrated
Assessment: Handbook of Methods and Procedures (available for download at www.agmip.org)

Details how to:

 install R and the required packages to run the AgMIP Climate scripts
 create climate scenarios from CMIP5 GCMs using a 30-year baseline daily weather dataset

The guide also outlines a workflow that can be modified for application to your own climate
data.

This guide and workflow are under continuous development and we expect to add new
capabilities and sections in future versions. The methods and scenarios here are intended for
AgMIP research and may not be suitable for other applications. Please contact Nicholas Hudson
([email protected]) if you have any questions or comments.

By Nicholas Hudson ([email protected]), CCSR | Columbia University

and Alex Ruane ([email protected]), NASA Goddard Institute for Space Studies
With special thanks to Yunchul Jung (University of Florida) and Sonali McDermid (NASA
GISS)
 Background - 2

Contents
Background ................................................................................................................................. 3
Installation....................................................................................................................................... 3
Download and Install R .............................................................................................................. 4
Download and Install Packages ............................................................................................... 5
Downloading AgMIP Climate Scenario Generation Scripts and Data ....................................... 9
Creating folders for R scripts and input data .............................................................................. 9
Downloading R scripts and data from WebDrive ................................................................. 10
Creating baseline .AgMIP files with “AgMIP Excel File Template_v2.0.xls” ........................ 12
Opening “AgMIP Excel File Template.xls” ............................................................................. 13
Creating baseline .AgMIP files with the enabled macro .......................................................... 14
Creating baseline .AgMIP files without the enabled macro ..................................................... 16
Running AgMIP Climate scripts ............................................................................................... 17
Explanation of input variables to be changed in the run scripts ............................................ 17
Modifying variables in the run scripts ...................................................................................... 24
Sourcing the run scripts ............................................................................................................ 27
Explanation of output files ........................................................................................................ 28
Suggested workflows for the AgMIP Climate run scripts ........................................................ 32
run_agmip_farmclimate.R ..................................................................................................... 33
run_agmip_simple_delta.R.................................................................................................... 34
run_agmip_simple_mandv.R ................................................................................................ 35
run_agmip_simple2full.R ...................................................................................................... 37
Creating “full” files from “run_agmip_simple_delta.R” outputs ...................................... 37
Creating “full” files from “run_agmip_simple_mandv.R” outputs ................................... 38
Next Steps… ................................................................................................................................. 39
Appendix 1: Creating .AgMIP files in Excel ................................................................................ 40
Appendix 2: Example file for “agmip_farmclimate.R” ................................................................ 42
Appendix 3: Example file for “agmip_simple_delta.R” and “agmip_simple2full.R”.................. 43
 Background - 3

Background
Version 2 of the Guide for Running AgMIP Climate Scenario Generation Tools with R
substantially reorganizes the sections to outline and establish a more logistically pragmatic
workflow. New sections or sections that have been substantially updated are marked with green
stars ().

This version also includes scripts, “agmip_simple_mandv.R” and “run_agmip_simple_mandv.R”

to apply mean and variability changes derived from all 20 GCMs, 3 time scenarios (Near-term
(2010-2039), Mid-Century (2040-2069), and End-of-Century (2070-2099)), and 2 RCPs (4.5 and
8.5). This script requires a new package, MASS, to fit statistical distributions and calculate
adjustments for the generated scenarios.

Also, the scripts “agmip_farmclimate.R”, “run_agmip_farmclimate.R”, “agmip_simple_delta.R”,

“run_agmip_simple_delta.R”, “agmip_simple2full.R”, and “run_agmip_simple2full.R” have all
been updated and should be downloaded.

Installation

This section explains how to install R and the packages necessary to run the climate scripts.

R is a free environment that can be used for statistical analysis and graphic development. To run
the scripts properly, packages are required to add functionality to R. These packages are free,
easy to download, and importantly must be loaded, but not reinstalled, every time you begin a
new R session. The AgMIP Climate Scenario Generation scripts that are described in this Guide
have been designed to load the required packages automatically as long as the packages have
been properly installed.
 Installation - 4

Download and Install R

Download the most recent version of R from <http://cran.r-project.org/bin/windows/base/>. The

image below shows a screenshot from the provided link to the R website. As you can see in the
below image, the most recent version of R is 3.0.1 (as of the publication of this guide). If there is
a more recent version of R, you should download that version. To download the installation file
in your web browser, click on the link indicated by the red arrow. Run the downloaded .exe file
and follow the steps of the installation wizard. After the installation is complete, open R.

Note: The R website provides a lot of helpful information if you are experiencing any
difficulties downloading or installing R onto your computer. Also, there are versions of R
available for Mac OS <http://cran.r-project.org/bin/macosx/> and Linux <http://cran.r-
project.org/bin/linux/>. Again, the R website is very useful so if you are installing R on
either of these platforms and are experiencing any difficulties, your questions may be
answered by information provided by this website.
 Installation - 5

Download and Install Packages

1. After installing R onto your computer, you will need to install the “R.matlab”, “R.utils”, and
“MASS” packages. Let’s start with the “R.matlab” package. You can perform this action by
either
 Selecting R: Packages-> Install package(s)… from the menu bar (shown by the red arrow
below) or by
 Typing the command

install.packages("R.matlab")

into R Console (the orange arrow below).

 Installation - 6

After selecting the nearest CRAN mirror, R will install the selected package “R.matlab” as well
as the dependent packages “R.oo” and “R.methodsS3” to your package library. Occasionally the
closest mirror does not work. If this is the case, simply try a different location. A successful
install will display the following message in R Console:

package ‘R.oo’ successfully unpacked and MD5 sums checked

package ‘R.methodsS3’ successfully unpacked and MD5 sums checked
package ‘R.matlab’ successfully unpacked and MD5 sums checked

IMPORTANT: The next step, Step 2, is crucial for the installed packages to run correctly.
The packages must be loaded, but not reinstalled, every time you begin a new R session
to perform the operations required by the provided climate scenario scripts. However,
the provided scripts described in this Guide automatically load the necessary packages with
the 3 line code shown below:

library <- c("R.matlab","R.utils")

lapply(library, require, character.only = T)
rm(library)

Thus, if you will only be running the provided climate scenario scripts, you can skip Step
2 and proceed to Step 3. If you are designing your own scripts and would like to retain the
functionality of the provided scripts you will either need to incorporate the three line code
above or follow Step 2 to load the packages.
 Installation - 7

2. Load “R.matlab” package. You can perform this action in one of two ways.
 You can select R: Packages-> Load package… from the menu bar (shown by the red
arrow below), which brings up a pop-up box titled “Select one.” Choose “R.matlab” as
indicated by the orange arrow.
 Alternatively, you can type the command

library(R.matlab)

into R Console as is indicated by the yellow arrow below.

 Installation - 8

When loading R.matlab, R will automatically load the dependencies, R.oo and R.methodsS3. R
Console’s output will inform you if all three packages were successfully loaded. The red arrow
below points to the lines indicating “R.oo” and “R.methodsS3” were successfully loaded, while
the orange arrow points to the “R.matlab” line.

3. Repeat steps 1 and 2 (pages 4-7) to install and load the packages “R.utils” and “MASS”.

IMPORTANT: The “MASS” package will be used by “agmip_simple_mandv.R” and has

been added to the list of required packages for Version 2.0 of the Guide. If you are
intending to run the script “run_agmip_simple_mandv.R”, you will have to install the
“MASS” package. Otherwise it is not necessary to install this package.
 Downloading AgMIP Climate Scenario Generation Scripts and Data - 9

Downloading AgMIP Climate Scenario Generation Scripts and Data

The following section explains:

1. The folder hierarchy necessary for climate scripts and data to function properly
2. How to download the climate scripts and data
3. Where to place these files within your newly created folder structure

Creating folders for R scripts and input data

AgMIP climate scripts require the below directory structure. We recommend that you use this
folder hierarchy as this is the easiest approach for running the AgMIP Climate Scenario scripts.
The hierarchy of the folders should look as follows (where blue = folders, purple = files, green =
description, red = important information):
 Downloading AgMIP Climate Scenario Generation Scripts and Data - 10

We now provide you with the folder structure already created. The first link of the next section,
Downloading R scripts and data from WebDrive, is the zipped folder structure that already
contains the R scripts, test files, AgMIP Excel file template, WorldClim datasets and latitude and
longitude datasets for GCMs in the correct folder locations. Additionally, you will have to the
GCM climate data and place these files into “~/R/data/CMIP5/climfiles”.

IMPORTANT: R is case sensitive so it is important to preserve the downloaded folder

hierarchy for the AgMIP Climate scripts to function correctly.

Downloading R scripts and data from WebDrive

The next step will be to download the climate data and R scripts from WebDrive (links provided
on the next couple pages). This is NASA Goddard’s Online File Depot and has been set up by
Alex Ruane. To gain access to these files, use the username and password provided below.

WebDrive Log In Information

Username aruane
Password AgMIPRRTs
Expiration Date August 24, 2013

The provided links have a 30 day expiration date and the files were posted on July 25, 2013, and
thus will not be available after August 24, 2013. If you are attempting to download these files
after this date, contact either Alex Ruane at [email protected] or Nicholas Hudson at
[email protected].

You will be downloading GCM files that use RCP 4.5 and RCP 8.5 as well as the latitude and
longitude files needed to properly read the GCM files.

Not all of the files that you will be downloading will be used in the guide, but they will be
discussed in future versions.

Below are the links for the required input data and R scripts along with a brief description of the
files and the folder destination where the files should be placed within your newly created folder
structure:
 Downloading AgMIP Climate Scenario Generation Scripts and Data - 11

R scripts, test climate files, and AgMIP Excel File Template download location:
https://webdrive.gsfc.nasa.gov/longauth/600/nicholas.hudson/DAFJtYC

1. The above link is the zipped folder structure containing the R scripts, test files, AgMIP
Excel file template, WorldClim datasets and latitude and longitude datasets for GCMs in
the correct folder locations. We advise that you download the most recent versions of
these scripts to ensure optimal performance and most robust analysis.

Script Name Brief description of functionality

Returns the i and j coordinates of a given location given its
acr_findspot.R
latitude and longitude and a models lat and lon arrays
Formerly “acr_agmip022.R” and “acr_agmip021.R”, produces
agmip_farmclimate.R monthly climate files from WorldClim data for n farms around
the seed weather station. UPDATED for Version 2.0
Runs “agmip_farmclimate.R” to produce monthly climate files
run_agmip_farmclimate.R
in AgMIP format. UPDATED for Version 2.0
Creates delta scenarios from CMIP5 GCMs and BCSD.
agmip_simple_delta.R
UPDATED for Version 2.0
Runs “agmip_simple_delta.R” to produce basic future scenario
run_agmip_simple_delta.R
files in .AgMIP format. UPDATED for Version 2.0
Formerly “acr_agmip100.R”, adjusts a climate time series for
agmip_simple_mandv.R
AgMIP mean and variability scenarios. NEW for Version 2.0
Formerly “acr_agmip120.R”, runs “agmip_simple_mandv.R” to
run_ agmip_simple_mandv.R produce climate time series in AgMIP format.
New for Version 2.0
Converts basic future scenarios (Srad, Tmax, Tmin, P) output
from “agmip_simple_delta.R” and “agmip_simple_mandv.R”
agmip_simple2full.R
into full future scenarios with relative humidity-controlled vapor
pressure based upon daily Tmax. UPDATED for Version 2.0
Runs “agmip_simple2full.R” to produce full future scenario files
run_agmip_simple2full.R
in .AgMIP format. UPDATED for Version 2.0
acr_agmip2metric.R Produces a record of climate metrics in a given season
run_metrics.R Runs “acr_agmip2metrics.R”

The R scripts are all located in “~/R/r”. This zip file also comes with a test baseline file,
“USAM0XXX.AgMIP” located in “~/R/data/Climate/Historical” and an example output file
from “run_agmip_simple_delta.R” and “run_agmip_simple2full.R” that can be found in
“~/R/data/Climate/Fullscenario”. Additionally, the zipped folder structure contains “AgMIP
Excel File Template v2.0.xls” in the folder “~/R/data/Climate//Historical” for creating baseline
 Creating baseline .AgMIP files with “AgMIP Excel File Template_v2.0.xls” - 12

.AgMIP files. This Excel template file uses a Visual Basic macro to create properly formatted
base files and has been designed to place the newly created base files into the same directory in
which the Excel template file is located. Therefore if you will be using “AgMIP Excel File
Template v2.0.xls” to create your baseline .AgMIP files, the Excel file will not have to be
moved. Lastly, the zip file contains WorldClim datasets in “~/R/data/WorldClim” and latitude
and longitude datasets for GCMs in “~/R/data/CMIP5/latlon”.

NOTE: We recommend that you keep the zip file containing the R scripts, the Excel
template file and the .AgMIP test file as a back-up in the event that these files become
corrupted. This is not necessary for the other zip files you will be downloading in the
remaining four links.

2. Place the remaining files listed below (all CMIP5 input files including meanpr, fwetpr1,
meantasmax, meantasmin, stdtasmas, and stdtasmin) in “~/R/data/CMIP5/climfiles”

Mean precipitation and the frequency of wet days (meanpr and fwetpr1) file download location:
https://webdrive.gsfc.nasa.gov/longauth/600/nicholas.hudson/Fmj7cYC

Mean maximum and minimum temperatures (meantasmax and meantasmin) file download
location:
https://webdrive.gsfc.nasa.gov/longauth/600/nicholas.hudson/NhUMVYC

Standard deviation of maximum and minimum temperatures (stdtasmax and stdtasmin) file
download location:
https://webdrive.gsfc.nasa.gov/longauth/600/nicholas.hudson/TdI3IC3

The files contained in these zipped folders should all be placed in “~/R/data/CMIP5/climfiles”
such that there are no folders located in “~/R/data/CMIP5/climfiles”, just the 360 climate files.

Creating baseline .AgMIP files with “AgMIP Excel File Template_v2.0.xls”

Before we begin running R, we will walk through an explanation of how to create baseline
.AgMIP files with “AgMIP Excel File Template_v2.0.xls”. We are currently seeking to create a
script that will help in the historical period gap filling and bias correction according to the
AgMIP protocols described in Section 4 of the AgMIP Guide for Regional Integrated
 Creating baseline .AgMIP files with “AgMIP Excel File Template_v2.0.xls” - 13

Assessment: Handbook of Methods and Procedures, but it is useful to be able to create .AgMIP
files in Excel regardless. If you prefer to create the baseline .AgMIP files manually, Appendix 1
provides a detailed outline for creating these files in Excel.

The baseline .AgMIP file should contain the 31-year (1980-2010) daily historical climate data
for a particular station or set of climate data. This section will explain how to:
1. Open the Excel file and enable macros
2. Enter your climate data into the spreadsheet and create a baseline .AgMIP file using the
macro enabled functionality
3. Create baseline .AgMIP files without the macro

Opening “AgMIP Excel File Template.xls”

The provided baseline AgMIP creation template was designed to quickly create properly
formatted .AgMIP files to be used throughout the remainder of this guide. If you have already
designed your baseline files, you can skip this subsection.

NOTE: This template Excel file automatically produces baseline .AgMIP files within the
folder in which “AgMIP Excel File Template_v2.0.xls” is saved. Accordingly, we
recommend that you save this template file to “~/R/data/Climate/Historical” so that the
created .AgMIP baseline files are placed in the correct folder location and do not have to
be moved later.

The spreadsheet includes a Visual Basic macro (essentially an Excel script designed to make
complicated or redundant tasks easier) which has been designed to assist with the creation of the
.AgMIP file. This spreadsheet’s macro is compatible with all Windows versions of Excel
created since 2003. If you are using a Mac and running Excel 2008, you will not be able to run
this macro as Mac’s 2008 version of Excel does not use Visual Basic. All other versions of
Excel should be able to run this macro. If you are unable of running the macro, or do not wish to
enable this functionality, the template can still be used to produce properly formatted baseline
.AgMIP files as described in the subsection, Creating baseline .AgMIP files without the enabled
macro.

To retain the ability of the macro, you will have to enable the macro when you open “AgMIP
Excel File Template_v2.0.xls”. Each version has a different way of enabling the macro.
Generally, when you open the Excel file, a security alert will appear prompting you to decide
whether to enable the macro or disable this feature. Enabling the macro will retain the
 Creating baseline .AgMIP files with “AgMIP Excel File Template_v2.0.xls” - 14

functionality that is discussed in the next step. If you disable the macro, you can skip the next
subsection and proceed to the subsection, Creating baseline .AgMIP files without the enabled
macro, to learn how to use the template without the macro.

If you are having difficulties enabling the macro, the Windows Office website has helpful
information on enabling macros for Excel versions 2003, 2007 and versions 2010 and 2013.

Creating baseline .AgMIP files with the enabled macro

After enabling the macro, you should see the cover sheet, Input Data, of the spreadsheet.
Essentially all you have to do to create the baseline .AgMIP file is fill in all of the light green
fields. Specifically:

1. Enter the information for your baseline file header into the "User Entered Values" section
on the left in the light green fields. This includes filling out information for the header of
your .AgMIP file to be created. Currently the AgMIP Climate scripts are not designed to
automatically use this information, however we highly recommend that you fill in these
fields to properly document the data. There are six “User Entered Values” required for
the header which should be unique for each station’s set of climate data.

8 digit baseline .AgMIP file name - The first 4 digits are used to describe the location of
your climate (meteorological) station. The first 2 digits are an abbreviation for the
country, which can be found at the website <http://www.web-l.com/country-codes/> (e.g.
US = United States). The second 2 digits refer to the specific site location (e.g. AM =
Ames, Iowa). The fifth through eighth digits (0XXX) should remain unchanged. For
example, a file created for Ames, Iowa, USA would be named “USAM0XXX.AgMIP”
and “USAM0XXX” would be entered into this field. The naming convention will be
described in further detail in the subsection, Explanation of output files.

Latitude (LAT) – latitude of the station in degrees North

Longitude (LONG) – longitude of the station in degrees East

Elevation (ELEV) – elevation of the station in meters

Thermometer height (REFHT) - the height of the station thermometer in meters above
the entered station elevation
 Creating baseline .AgMIP files with “AgMIP Excel File Template_v2.0.xls” - 15

Anemometer height (WNDHT) - the height of the station anemometer in meters above
the entered station elevation

2. Arrange your 31-year (1980-2010) daily climate data in the proper column order (where
Srad = solar radiation, Tmax = temperature maximum, Tmin = temperature minimum,
Rain = precipitation, Wind = wind speed, Dewp = dew point, Vprs = vapor pressue, and
Rhum = relative humidity) into the table in the bottom left corner of the sheet “Input
Data” (in the light green fields).

You should fill missing values with -99. If you do not have data for Wind and/or Rhum,
you can retrieve this data from the Ag-MERRA dataset. Dewp and Vprs will require
additional conversion and can be left as missing (entered as -99) for the purposes of the R
routines described in this Guide.

Upon entering the data correctly into these columns, the orange boxes’ color should turn
light green and display “Yes”.

3. Once the data has been arranged correctly, simply press the green button titled “Create
.AgMIP file” to produce your new baseline .AgMIP file. This new file will be created in
the same file you have positioned “AgMIP Excel File Template_v2.0.xls”. Confirm the
presence of your new baseline .AgMIP file in “~/R/data/Climate/Historical”. If you have
successfully produced your baseline .AgMIP file, you can proceed to the next section,
Running AgMIP Climate scripts.
 Creating baseline .AgMIP files with “AgMIP Excel File Template_v2.0.xls” - 16

Creating baseline .AgMIP files without the enabled macro

NOTE: This subsection is only for individuals who have not been able to enable the
macro or who have opted not enable the macro. If you have successfully created your
.AgMIP baseline file, you can proceed to the next section, Running AgMIP Climate
scripts.

If the macro will not work or you have chosen not to enable the macro, the template can still
useful for you. Follow steps 1-2 in Creating baseline .AgMIP files with the enabled macro to
correctly enter your data into the first sheet (Input Data) of “AgMIP Excel File
Template_v2.0.xls”.

After you have entered your header information and climate data into the light green fields, go to
the second sheet, Baseline Data. This shows the properly formatted data and header. All you
have to do to create the .AgMIP file is to save this sheet. To do this, follow these steps:
1. Select “File > Save As”
2. Select the location “~/R/data/Climate/Historical/”
3. In “File name:” enter the name of your baseline file in quotes. That is, enter the name
you have entered into the field 8 digit baseline .AgMIP file name on the sheet “Input
Data” with the .AgMIP extension. For example, if you entered “USAM0XXX” into that
field, enter “USAM0XXX.AgMIP” into the “File name:” field including the quotes.
4. In “Save as type:” select “Formatted Text (Space Delimited)
5. Select “Save”
6. A warning will appear alerting you that this format will not support multiple sheets.
Select “OK”.
7. There will be another warning about compatibility issues. Select “Yes”.
8. Your file should now be saved, however, you will want to close the now altered Excel
spreadsheet and select “Don’t Save” to ensure the initial “AgMIP Excel File
Template_v2.0.xls” is not altered in this process.

The macro actually works around this “Don’t Save issue” by copying and pasting the data from
the second sheet (Baseline Data) onto a new workbook. This can be difficult though as older
versions of Excel do not have the functionality of Paste Special as the newer versions (both
numerical and columnar formatting need to be retained). We encourage users to follow the
above workflow and only paste the data into a new workbook if they feel comfortable ensuring
that the formatting of the data is not lost in the pasting process.
 Running AgMIP Climate scripts - 17

Confirm the presence of your new baseline .AgMIP file in “~/R/data/Climate/Historical”. If you
have successfully produced your baseline .AgMIP file, you can proceed to the next section,
Running AgMIP Climate scripts.

Running AgMIP Climate scripts

Now that you have downloaded and installed R, downloaded the input data and R scripts, placed
these files into the proper folder structure and created your baseline .AgMIP files, you are ready
to run the AgMIP Climate scripts in R The following section will explain:
1. The input variables that will be modified for each of the run scripts
2. How to modify the run scripts
3. How to source the run scripts
4. An explanation of the output files
5. A suggested workflow for each of the provided AgMIP Climate scripts

Explanation of input variables to be changed in the run scripts

We will be changing the run scripts to reflect the information for your specific location and
analytical requirements. The run scripts all begin with “run” and call the scripts that are
identically named but do not begin with “run” (e.g. “run_agmip_farmclimate.R” calls
“agmip_farmclimate.R” and run_agmip_simple_delta.R” calls “agmip_simple_delta.R”). These
scripts have been designed so that you only have to edit the run scripts and should not have to
open the other scripts.

Essentially, the run scripts set the variables and parameters of the analysis. These run scripts are
also designed to loop through multiple scenarios, thus producing many .AgMIP files with
multiple scenario changes imposed upon the baseline data (different emission scenarios or future
time periods, for example).

All of the run scripts have been similarly designed and share many of the same input variables.
To simplify the explanation for using these AgMIP Climate scripts, we have provided a list of
the input variables in this subsection that will need to be changed prior to running, or “sourcing”,
of the scripts. To clarify, each run script will require that some, but not all, of the input variables
listed in this subsection be defined.
 Running AgMIP Climate scripts - 18

We recommend that you read through this subsection to become familiar with the input variables
that you will be changing. It is our intention that this subsection will be used as a reference later
if you have a question about a particular input variable. In the next subsection, Modifying
variables in the run scripts, we will describe how to change these input variables.

Below is a screenshot of the “Input Variables” section of the script “run_agmip_simple_delta.R”.

Colored arrows identify the input variables that will need to be adjusted for this run script. T
The “#” symbol is used to “comment out” lines and provides you with information about the
input variables. The script skips lines that have been commented when it is being sourced.

The next few pages describe the input variables that you will be required to adjust prior to
sourcing the run scripts.
 Running AgMIP Climate scripts - 19

rootDir – This variable, as identified by the blue arrow in the screenshot on the previous page,
sets the location, or root directory, of your “~/R/” folder discussed in the subsection, Creating
folders for R scripts and input data. If you created the recommended folder structure, defining
this variable is straightforward. There is a line in every run script that reads:

rootDir <- '*** your directory here ***\\R\\'

Simply replace the text “*** your directory here***” with the location of your newly created R
directory in the script using double forward slashes (\\) to separate folders. For example, if the
location of the R folder is

C:\Users\Your Name Here\Desktop\R\

then the rootDirshould look as follows

rootDir <- 'C:\\Users\\Your Name Here\\Desktop\\R\\'

IMPORTANT: The variable rootDirshould not change from run to run. We recommend
that you save the run script with updated rootDirto reflect the location of “~/R/” so you do
not have to enter this information for every run. The other input variables should be
changed with each new run to reflect the specific parameters of your current analysis.

basefile – This is the 8 digit baseline .AgMIP file name described in the subsection Creating
baseline .AgMIP files with the enabled macro and identified by the red arrow on the previous
page. The first four digits describe the location of the station/site while the last four digits denote
the type of scenario that was imposed on the historic data. Specifically, the first 2 digits are an
abbreviation for the country, which can be found at the website <http://www.web-l.com/country-
codes/>, while the second 2 digits refer to the specific site location and are up to you to assign.
For a baseline file, the last four digits should be “0XXX”. For example, we have defined the
basefile for Ames, Iowa, USA to be “USAM0XXX”. Thus the run script input variable line
would look like

basefile <- 'USAM0XXX'

More information about the naming convention can be found in the subsection, Explanation of
output files.
 Running AgMIP Climate scripts - 20

basedecs – This variable, also identified by the red arrow in the screenshot, assigns the
beginning and end year of the dataset’s 30-year time interval. Typically, the test file runs from
January 1, 1980 to December 31, 2009, thus the years entered for the test file’s 30-year time
interval are 1980 and 2009. To assign Error! Reference source not found. to run from 1980 to
009, this input variable would be assigned as

basedecs <- c(1980,2009)

If you have data for 2010, you have the option of either selecting the time period from 1980 to
2009 or 1981 to 2010. If you chose to select 1981 to 2010, you would enter the input variable as

basedecs <- c(1981,2010)

to assign Error! Reference source not found. to run over this time scale.

run.gcms – This variable, identified by the orange arrow, is used to control which GCMs will be
used to create the output files. The run scripts are set to run through all 20 of the GCMs will the
following line:

run.gcms <- 1:20

The script is designed to run through the GCMs as they are ordered in the variable gcmname.
The ordering of the GCMs are provided in the commented lines directly above this input variable
(as can be seen in the screenshot). Say, for example, you want to run the script for BNU-
ESM2M, HadGEM2-CC and MIROC5 which are positioned as the 3rd, 10th and 15th in gcmlist.
You would then define run.gcms as

run.gcms <- c(3,10,15)

If you only want to run the first five GCMs follow the same procedure and enter the line

run.gcms <- c(1,2,3,4,5)

Or alternatively,

run.gcms <- 1:5

 Running AgMIP Climate scripts - 21

run.rcps – This input variable, identified by the yellow arrow, is used to control which
emissions scenarios (RCPs) will be used to create the output files where 1 = historical, 2 = RCP
2.6, 3 = RCP 4.5, 4 = RCP 6.0, and 5 = RCP 8.5. As can be seen in the screenshot, the run script
“run_agmip_simple_delta.R” is set to run RCP 4.5 (3) and RCP 8.5 (5) with the following line:

run.rcps <- c(3,5)

If you wish to produce files from another emissions scenario simply redefine run.rcps. For
example, if you only want to run the script from the emissions scenario RCP 8.5, set the input
variable to 5 using the following line:

run.rcps <- 5

If you want to run the script for all of the RCPs you can use the line

run.rcps <- c(2,3,4,5)

Or alternatively,

run.rcps <- 2:5

IMPORTANT: Some of the run scripts (“run_agmip_simple_mandv.R” in particular)

require a large amount of local memory. As such, we recommend that you run one
emissions scenario at a time for “run_agmip_simple_mandv.R”. If the script breaks while
you are running one of the AgMIP Climate scripts due to memory issues, consider reducing
the number of emissions scenarios or number of future the time periods. After the run has
successfully completed, reboot your computer (to reset your local memory) and run the
other time periods and emissions scenarios you will require.

run.decs – Another input variable, as identified by the green arrow, used to control the output
files produced by the run scripts. This input variable is used to control which time periods will
be used. Below is a table of the three preset future time periods.

Future time period run.decs values First year Last year

Near-term 1 2010 2039
Mid-Century 2 2040 2069
End-of-Century 3 2070 2099
 Running AgMIP Climate scripts - 22

Similar to run.gcms and run.rcps, this variable is easily adjusted. Below is a line demonstrating
how to produce output files for Near-term and End-of-Century future time scenarios

run.decs <- c(1,3)

If you wish to produce files over just the Mid-Century time period, use the line provided below.

run.decs <- 2

end.code – This input variable, used exclusively in “run_agmip_simple2full.R”, denotes the last
two (seventh and eighth) digits of the files to be adjusted. For example, if you want to adjust all
of the files of the structure “USAM**XA.AgMIP” with a baseline file of
“USAM0XXX.AgMIP” to the full format, the end.code would be “XA”. This would set the run
script to cycle through the scenarios (defined by run.gcms, run.rcps, and run.decs) of all the
files in “~/R/data/Climate/Simplescenario” that begin with “USAM” and end with “XA”.

seedfile – Similar to basefile, seedfileseedfileseedfileseedfile is the 8 digit code of your baseline

climate file. The input variable seedfile is used in the script “run_agmip_farmclimate.R” as this
will be the dataset from which other local farm sites’ climate files will be constructed. For
example, the 8 digit code of seedfile would be “KEMB0XXX” if the baseline AgMIP file was
named “KEMB0XXX.AgMIP”.

shortregion – Another input variable used exclusively with “run_agmip_farmclimate.R”,

shortregion is a 2 digit identifier used for a particular region for which you will be producing
multiple files. Typically, it is sufficient to simply strip of the country code. For example, the
country code “KE” can be stripped off the seedfile “KEMB0XXX” seedfileleaving the regional
code “MB”. The resulting output files from “run_agmip_farmclimate.R” will be named
“MB010XFX.AgMIP”, “MB020XFX.AgMIP”, “MB030XFX.AgMIP”…

headerplus – This variable allows you to enter additional information into the first line of the
produced AgMIP files.
 Running AgMIP Climate scripts - 23

sitelat – Another input variable used exclusively with “run_agmip_farmclimate.R”. This input
variable defines the series of site latitudes for which you are creating climate baseline files. This
variable should be defined in terms of degrees North such that the values range from -90°N
(South Pole) to 90°N (North Pole).

For example, below is the line from the run script that will produce 3 output .AgMIP files for
farms at latitudes -0.7°N, -0.6°N and -0.75°N respectively.

sitelat <- c(-00.70, -00.60, -00.75)

sitelon – Same as sitelat, but with longitude. This variable should be defined in terms of degrees
East such that 90°W should be entered either as -90°E or as 270°E. For example, below is the
line from the run script.

sitelon <- c(37.54, 37.58, 37.69)

This example denotes that the run script will produce 3 output .AgMIP files for farms at
longitudes 37.54°E, 37.58°E and 37.69°E respectively.

datashort – This variable is used to define your sub-region for WorldClim files and is used
exclusively by the script “run_agmip_farmclimate.R”. Your region is determined by the table
below and you should enter your region into the input variable datashort.

Datashort Region Name S. Lat N. Lat W. Lon E. Lon

EAfrica Eastern Africa 20°S 22°N 20°E 53°E
WAfrica Western Africa 3°N 25°N 18°W 15°E
SAfrica Southern Africa 36°S 8°S 11°E 51°E
Pakistan Pakistan 23°N 38°N 60°E 80°E
IGB Indo-Gangetic Basin 15°N 38°N 65°E 97°E
SIndiaSriLanka S. India and Sri Lanka 5°N 30°N 70°E 90°E

If, for example, your region is located at 5°N, 35°E, you would enter the input variable as

datashort <- ‘EAfrica’

due to your location in the subregion of Eastern Africa.

 Running AgMIP Climate scripts - 24

Modifying variables in the run scripts

NOTE: For the purposes of this tutorial, we recommend that you perform the following
modifications of the AgMIP Climate scripts using the R GUI to gain some familiarity with
R’s user interface. However, if you are familiar with R and feel more comfortable
amending the scripts in your preferred text editor, feel free to do so.

This subsection explains the steps that are required to prepare a run script for use on your
computer. This subsection generalizes how to make the adjustments to the script. The
subsection, Suggested workflows for the AgMIP Climate run scripts, explains specifically how
to run each of the AgMIP Climate run scripts. Like the previous subsection, Explanation of
input variables to be changed in the run scripts. We recommend that you read through this
subsection to get an idea of how to modify the run scripts and refer to it later if you have
questions when working through the workflows presented in the subsection, Suggested
workflows for the AgMIP Climate run scripts. The following section will explain:
1. How to open a script in R
2. How to modify rootDirto tailor the run script for your computer
3. How to modify the other input variables
 Running AgMIP Climate scripts - 25

We will begin by opening the run script you are interested in running. After opening R, there are
a couple ways you can open the run script. You can either

• Select “File > Open script…” from the menu bar along the top of the R window as
indicated by the red arrow, or

• Press the open button, , in the toolbar (hidden in the below image by the drop-down
window).

If you followed the recommended folder structure outlined in the subsection, Creating folders for
R scripts and input data, the scripts will be located in the folder “~/R/r/”.
 Running AgMIP Climate scripts - 26

Once you have opened the run script in the R editor, the next step is to adjust rootDirto reflect
the location of your “~/R/” folder. Scroll down section “Input variables” below the run script
heading to the line that reads:

rootDir <- '*** your directory here ***\\R\\’

Enter the path to your root directory, that is the location of your “~/R/” folder, discussed in the
subsection, Creating folders for R scripts and input data in the run script using double forward
slashes (\\) to separate the folders. For an example, refer to rootDir.

NOTE: If you will be running these scripts for multiple station locations, we recommend
that you save the run script at this point in time. The input variable rootDirshould not
change from run to run and thus you can save the run script to avoid having to adjust this
variable for every run. The other input variables will be changed for different runs, so
saving the script here is a logical saving point.

After rootDiris assigned, you will not have to change any of the other folder locations as the
folder structure is hardwired into the scripts. The AgMIP Climate scripts were intentionally
designed this way to make this process as simple as possible.

After saving the run script, you will have to change the input variable information prior to every
run. You can edit the script either in R editor (as will be demonstrated below) or another text
editor of your choosing. We will continue to use R editor in this Guide.

Each AgMIP Climate script has a section for the input variables that must be assigned to run the
script successfully. The section, Suggested workflows for the AgMIP Climate run scripts,
outlines the input variables that will need to be defined. These input variables will need to be
defined prior to every run. After properly defining these input variables, you would be ready to
run, or source, the AgMIP climate script.

IMPORTANT: At this point you have to save the run script to “~/R/r/”. We recommend
that you save the script as a separate file with a unique name (e.g.
“run_agmip_farmclimate_stn1” or “run_agmip_simple2full_USAM_delta3”) to reflect the
particular station, dataset or analysis. This will retain the initial AgMIP run script as a
template for future analyses.
 Running AgMIP Climate scripts - 27

Sourcing the run scripts

After defining the input variables of your run script and saving the run script with a unique name
to “~/R/r/”, return to the R Console window. To run your amended run script, select “File >
Source R code…” from the menu bar as is indicated by the red arrow in the screenshot below. It
is important that you are in the R Console, otherwise “Source R Code” will not be an option in
the File dropdown menu.

After you select “Source R code…”, navigate to “~/R/r/” and select your amended run script.
Typically the run scripts will take a few hours to run as they are batch creating multiple files
based on a variety of scenarios.

The next section, Explanation of output files, describes the naming convention that is used with
the 8 digit AgMIP file names. The following section, Suggested workflows for the AgMIP
Climate run scripts, outline suggested procedures for using the different AgMIP run scripts.
 Running AgMIP Climate scripts - 28

Explanation of output files

The provided AgMIP run scripts create a series of files that are named with an eight digit code.
This naming convention was created to help convey details of the scenarios so that they may be
understood by other AgMIP participants and the AgMIP IT tools.

Below is a brief explanation of the key (pages 30-31) for this code. The file in the figure below is
the first file that would be created from running “run_agmip_simple_delta.R” with the preset
parameters using the given test AgMIP baseline file, “USMA0XXX.AgMIP”.

The first 4 digits, as described by 8 digit baseline .AgMIP file name in the subsection Creating
baseline .AgMIP files with the enabled macro and basefilein the subsection Explanation of input
variables to be changed in the run scripts, are used to describe the location of the climatological
(meteorological) station where your historical dataset was collected. In the above example, the
code “USAM” is used to describe the location where the first 2 letters are an abbreviation for the
country (US = United States). The website, <http://www.web-l.com/country-codes/>, provides 2
letter codes for countries and we recommend that you use these abbreviations for the first two
digits of your 8 digit code.

The second 2 digits refer to the site location and are up to you to define. For the code
“USAMCAXA”, the “AM” is used to denote Ames, Iowa. Use your discretion when choosing
 Running AgMIP Climate scripts - 29

these digits. These digits should help create a unique code for your file so try to avoid redundant
digits.

The fifth digit describes the time period and emissions scenario. Generally, the run scripts are
designed to loop through multiple time periods and emissions scenarios when producing new
files and this digit is automatically assigned to reflect the parameters imposed upon the dataset.
In the example on the previous page, the fifth digit, C, denotes that the file uses RCP 4.5 over the
future time period from 2010-2039. A baseline AgMIP file has a zero (0) as the fifth digit
defining that the file’s time period runs from 1980-2009 and does not have an imposed emissions
scenario.

The sixth digit typically denotes the imposed GCM scenario from CMIP5. For the purposes of
many of the analyses that will be conducted in the future, the CMIP5 GCM outputs will be used
unless otherwise mentioned. In the example, the sixth digit is an “A”, which tells us that this
particular file had a GCM scenario imposed on the baseline data from ACCESS1-0. A baseline
AgMIP file has an X as the sixth digit denoting that there was no GCM used in the creation of
the file. Similar to the fifth digit, the sixth digit is typically assigned within the AgMIP run script
loops.

The seventh digit is used to impose additional downscaling or sensitivity tests on the baseline
dataset. Generally this variable is unchanged when using the scripts described in this Guide
unless you impose downscaling or scenario methodology independently. As a result, this digit is
usually X, denoting that there has been no additional downscaling.

The eighth digit tells us the type of scenario that has been imposed for this particular file. For
the example code on the previous page, “USAMCAXA”, the eighth digit, “A”, tells us that there
has been a mean change imposed a calculated from a GCM. This digit is typically assigned by
the loop in the run script, but in when using the script “run_agmip_simple2full.R” you will need
to identify this variable to specify files that you would like to be expanded to full files. The
eighth digit is an “X” for the baseline AgMIP files, defining the file to be a dataset of daily
observations.

The next two pages (pages 31-32) list the key for the fifth, sixth, seventh and eighth digits of the
AgMIP file naming convention. The first four digits are user defined and thus do not require a
key.
 Running AgMIP Climate scripts - 30

Fifth Digit is time period and emissions scenario:

0 = 1980-2009 baseline C = RCP4.5 2010-2039 (Near-term)
1 = A2-2005-2035 (Near-term) D = RCP6.0 2010-2039 (Near-term)
2 = B1-2005-2035 (Near-term) E = RCP8.5 2010-2039 (Near-term)
3 = A2-2040-2069 (Mid-Century) F = RCP2.6 2040-2069 (Mid-Century)
4 = B1-2040-2069 (Mid-Century) G = RCP4.5 2040-2069 (Mid-Century)
5 = A2-2070-2099 (End-of-Century) H = RCP6.0 2040-2069 (Mid-Century)
6 = B1-2070-2099 (End-of-Century) I = RCP8.5 2040-2069 (Mid-Century)
S = sensitivity scenario J = RCP2.6 2070-2099 (End-of-Century)
A = observational time period (determined in K = RCP4.5 2070-2099 (End-of-Century)
file) L = RCP6.0 2070-2099 (End-of-Century)
B = RCP2.6 2010-2039 (Near-term) M = RCP8.5 2070-2099 (End-of-Century)

Sixth Digit is source of Sixth Digit is GCM (if CMIP3 Sixth Digit is GCM (if CMIP5
baseline data (if baseline scenario – these are not scenario):
scenario): required for AgMIP full 0 = imposed values (sensitivity
X = no GCM used assessments): tests)
0 = imposed values (sensitivity X = no GCM used A = ACCESS1-0
tests) 0 = imposed values (sensitivity B = bcc-csm1-1
Q = Bias-corrected MERRA tests) C = BNU-ESM
T = NASA POWER A = bccr D = CanESM2
U = NARR B = cccma cgcm3 E = CCSM4
V = Bias-corrected CFSR C = cnrm F = CESM1-BGC
W = MERRA D = csiro G = CSIRO-Mk3-6-0
Y = NCEP CFSR E = gfdl 2.0 H = GFDL-ESM2G
Z = NCEP/DoE Reanalysis-2 F = gfdl 2.1 I = GFDL-ESM2M
G = giss er J = HadGEM2-CC
H = inmcm 3.0 K = HadGEM2-ES
I = ipsl cm4 L = inmcm4
J = miroc3 2 medres M = IPSL-CM5A-LR
K = miub echo g N = IPSL-CM5A-MR
L = mpi echam5 O = MIROC5
M = mri cgcm2 P = MIROC-ESM
N = ncar ccsm3 Q = MPI-ESM-LR
O = ncar pcm1 R = MPI-ESM-MR
P = ukmo hadcm3 S = MRI-CGCM3
T = NorESM1-M
 Running AgMIP Climate scripts - 31

Seventh Digit is downscaling/scenario Eighth Digit is Type of Scenario:

methodology: X = Observations (no scenario)
X = no additional downscaling A = Mean Change from GCM
0 = imposed values (sensitivity tests) B = Mean Change from RCM
1 = WRF C = Mean Change from GCM modified by RCM
2 = RegCM3 D = Mean Temperature Changes Only
3 = ecpc E = Mean Precipitation Changes Only
4 = hrm3 F = Mean and daily variability change for Tmax,
5 = crcm Tmin, and P
6 = mm5i G = P, Tmax and Tmin daily variability change
7 = RegCM4 only
A = GiST H = Tmax and Tmin daily variability and mean
B = MarkSIM change only
C = WM2 I = P daily variability and mean change only
D = 1/8 degree BCSD J = Tmax and Tmin daily variability change only
E = 1/2 degree BCSD K = P daily variability change only
F = 2.5minute WorldClim
W = TRMM 3B42
X = CMORPH
Y = PERSIANN
Z = GPCP 1DD
 Suggested workflows for the AgMIP Climate run scripts - 32

Suggested workflows for the AgMIP Climate run scripts

This subsection details the specific workflows that should be used to run the AgMIP Climate
scripts. This section, Running AgMIP Climate scripts, has generalized how to run these scripts
and this section will explicitly outline how each of these scripts should be run.

If you have any questions about the input variables, refer to the subsection, Explanation of input
variables to be changed in the run scripts or simply click on the input variable of which you have
a question. The subsection Modifying variables in the run scripts explains how to prepare the
run script and the subsection Sourcing the run scripts demonstrates how to run the script. If you
have any questions with the naming convention imposed on the output files, please refer to the
subsection Explanation of output files.

In the overall workflow, this subsection picks up after you have successfully created your
baseline .AgMIP file as described in the section Creating baseline .AgMIP files with “AgMIP
Excel File Template_v2.0.xls”. This subsection then details how to:
1. Create new baseline AgMIP files for sites in the region of your climate station using
“run_agmip_farmclimate.R”.
2. Impose mean changes on the climate variables temperature maximum (Tmax),
temperature minimum (Tmin) and precipitation (Rain) based on the GCMs with different
emissions scenarios and across different time scales using “run_agmip_simple_delta.R”.
3. Impose mean and variability changes to the climate variables temperature maximum
(Tmax), temperature minimum (Tmin) and precipitation (Rain) based on the GCMs with
different emissions scenarios and across different time scales using
“run_agmip_simple_mandv.R”.
4. Convert file simple output files from either “run_agmip_simple_delta.R” or
“run_agmip_simple_mandv.R” to full files (including wind speed (Wind) and relative
humidity (Rhum) from the baseline AgMIP file and modified dew point (Dewp), vapor
pressue (Vprs) derived from changes to Tmax) using “run_agmip_simple2full.R”.

To reiterate, the run scripts are designed to batch produce a number of .AgMIP files by calling
the script of the same name but without the “run” prefix (e.g. “run_agmip_farmclimate.R” calls
“agmip_farmclimate.R”, “run_agmip_simple2full.R” calls “agmip_simple2full.R”). The run
scripts are designed to loop through multiple scenarios to reduce the number of times you will
need to run these scripts. The following workflows explain how these run scripts should be used
and have some information on how they can be tailored for your needs.
 Suggested workflows for the AgMIP Climate run scripts - 33

run_agmip_farmclimate.R

The run script “run_agmip_farmclimate.R” creates baseline .AgMIP files for a series of locations
(farms) in a given region. This script can be used to create climate files for a large number of
farm locations that are close to a central weather station where the historical climate series has
been quality controlled. If the farms are greater than ~100km away it may be better to pull the
sites directly from Ag-MERRA dataset.

The workflow is fairly simple if you have placed all of the files in the correct location as
described in Creating folders for R scripts and input data. All you will have to do is switch a
couple of the input variables in the run script prior to each run.

To run this script,

1. Open R and then open the run script “run_agmip_farmclimate.R” to edit the input
variables. You could also edit the run script in a text editor if you prefer.
2. Change the rootDirto reflect the location of the folder “R” and datashort to reflect your
WorldClim sub-region.
3. Save the updated run script as your template “run_agmip_farmclimate.R” script.
Adjust the input variables seedfile, shortregion, headerplus, sitelat, and
4. sitelon to reflect your station information (of the base file). For headerplus, simply enter
the location of the station (e.g. “Ames, Iowa, USA” or “Nioro, Senegal).
5. Save the amended script with a unique name (e.g. run_agmip_farmclimate_1 or
run_agmip_farmclimate_Station144) to “`/R/r/”.
6. Confirm the presence of your baseline file, “****0XXX.AgMIP” in
“~/R/data/Climate/Historical/”.
7. Source (run) the script from the R Console.
8. Try not to use your computer if possible to improve run time of script.
9. After the script has completed, the baseline .AgMIP files for a series of locations should
be located in ~\\R\\data\\Climate\\Historical\\. Confirm the presence of these files.

Although we did not provide you with a test file for this script, there is an example of an output
from “run_agmip_farmclimate.R” shown in Appendix 2. The example file demonstrates the
format of the .AgMIP files produced by this run script. This script should run quickly but will
take more time depending on the number of sites for which you are producing baseline .AgMIP
files.
 Suggested workflows for the AgMIP Climate run scripts - 34

Note: When closing R, you will be asked to save your workspace. This saves the working
environment (data, functions, etc.) and should not be necessary for the purposed of running
the AgMIP Climate scripts.

run_agmip_simple_delta.R

This script creates delta scenarios from CMIP5 GCMs and BCSD in the AgMIP standard format.
You can either use your baseline AgMIP file or the newly created AgMIP files produced by
“run_agmip_farmclimate.R” as the input basefilefor this run script. We are currently working
on a run script that would loop through a series of basefileto simplify larger batch runs.

To run this script,

1. Open R and then open the run script “run_agmip_simple_delta.R” to edit the input
variables. You could also edit the run script in a text editor if you prefer.
2. Change the rootDir to reflect the location of the folder “~/R”.
3. Save the updated run script as your template “run_agmip_simple_delta.R” script.
Adjust the input variables basefile and Error! Reference source not found. to reflect
he relevant information of your baseline AgMIP file. You can also adjust the variables
run.gcms, run.rcps, and run.decsrun.decs if you only require a subset of these input
variables.

IMPORTANT: If you are having issues completing the script due to local memory issues,
consider adjusting run.gcms, run.rcps, and run.decsrun.decs. Running subsets will
produce fewer output files and use less of your local memory. After completing such a
subset it is important to reboot your computer prior to running the next subset.

4. Save the amended script with a unique name (e.g. “run_agmip_simple_delta_Stn12.R” or

“run_agmip_simple_delta_Farm67.R”) to “`/R/r/”.
5. Confirm the presence of your basefile in “~\\R\\data\\Climate\\Historical\\”
6. Source (run) the script from the R Console
7. Try not to use your computer if possible to improve run time of script.
8. After the script has completed, the basic delta adjusted files should be located in
~\\R\\data\\Climate\\Simplescenario\\. Confirm the presence of these files.
 Suggested workflows for the AgMIP Climate run scripts - 35

The .AgMIP files produced by “run_agmip_simple_delta.R” only contain the climate variables
Srad, Tmax. Tmin, and Rain. If you require any of the other climate variables (Wind, Dewp,
Vprs, and/or Rhum) you can use “run_agmip_simple2full.R” to create full files. The subsection
Creating full files from “run_agmip_simple_delta.R” outputs explains how to do this.

If you chose to source “run_agmip_simple_delta.R” with the test file, “USAM0XXX.AgMIP” to

produce the simple future scenario files in .AgMIP format, you can check the first created file,
“USAMCAXA.AgMIP”, against the data shown in Appendix 3. However, the data shown in
this Appendix is the output from “run_agmip_simple_delta.R” and “run_agmip_simple2full.R”
so remember that the example displays data for wind speed (WIND), dew point (DEWP), vapor
pressure (VPRS), and relative humidity (RHUM) as well.

run_agmip_simple_mandv.R

The script “agmip_simple_mandv.R” applies mean and variability changes to temperature

maximum (Tmax), temperature minimum (Tmin) and precipitation (Rain) of the input baseline
.AgMIP file. The other climate variables (Srad, Wind, Dewp, Vprs, Rhum) are not adjusted by
this script.

Running this script is similar to “run_agmip_simple_delta.R” in that you should only have to
change the root directory (rootDir), adjust the input variables, and the run script will impose a
series of changes to the baseline files. Below is a suggested workflow for running
“run_agmip_simple_mandv.R”:

To run this script,

1. Open R and then open the run script “run_agmip_simple_mandv.R” to edit the input
variables. You could also edit the run script in a text editor if you prefer.
2. Change the rootDir to reflect the location of the folder “~/R”.
3. Save the updated run script as your template “run_agmip_simple_delta.R” script.
Adjust the input variables basefile and headerplus to reflect the relevant information of
your baseline AgMIP file. Change headerplus from “Ames, Iowa, USA” to the text
with the station or site location. We recommend that you leave the text “with mean and
daily variability changes for Tmax, Tmin and P”. You can also adjust the variables
run.gcms, run.rcps, and run.decsrun.decs to run a subset of these input variables.
 Suggested workflows for the AgMIP Climate run scripts - 36

IMPORTANT: This run script, “run_agmip_simple_mandv.R” will quickly use up your

local memory. We recommend that you only run one emissions scenario (as defined by
run.rcps) and one time period (as defined by run.decs) per run to ensure the script finishes
without encountering any memory issues. It is important to remember to restart your
computer after completing a run if you intend on running another analysis.

4. Save the amended script with a unique name (e.g. “run_agmip_simple_mandv_Stn12.R”

or “run_agmip_simple_mandv_Farm67.R”) to “`/R/r/”.
5. Confirm the presence of your basefile in “~\\R\\data\\Climate\\Historical\\”
6. Source (run) the script from the R Console
7. Try not to use your computer if possible to improve run time of script.
8. After the script has completed, the basic delta adjusted files should be located in
~\\R\\data\\Climate\\Simplescenario\\. Confirm the presence of these files.

The .AgMIP files produced by “run_agmip_simple_mandv.R” only adjust the climate variables
Tmax. Tmin, and Rain. The other climate variables (Srad, Wind, Dewp, Vprs, and Rhum) are
pasted into this file from the AgMIP file you specified as the basefile. If you require that Dewp
and Vprs are updated to reflect changes in Tmax, you can use “run_agmip_simple2full.R” to
create full files. The subsection Creating full files from “run_agmip_simple_mandv.R” outputs
explains how to do this.

IMPORTANT: The script “agmip_simple_mandv.R” occasionally has difficulties applying

the mean and variability changes without significantly changing the distribution and will
notify you that there is a poor fit. The script is designed to then loop through and try to apply
the changes two more times. If the run script is unable of applying the changes after three
tries, the script will fill in that particular month with -99 values.

If you encounter this issue, you can try to run the script again (after it has completed creating
the other output files and rebooting your computer) specifically for this file by using
run.gcms, run.rcps, and run.decs. If the problem persists, please contact us so we can help
you resolve this issue and produce the .AgMIP files you require for your research.
 Suggested workflows for the AgMIP Climate run scripts - 37

run_agmip_simple2full.R

The script “agmip_simple2full.R” converts basic future scenarios (Srad, Tmax, Tmin, Rain) into
full scenarios with relative humidity-controlled dew point and vapor pressure based upon daily
Tmax. The script fills Wind and Rhum with the data from the input baseline AgMIP file and
computes new values for Dewp and Vprs based on Tmax and Rhum.

The run script can be used for output AgMIP files from “run_agmip_simple_delta.R” and from
“run_agmip_simple_mandv.R”. Both have slightly different workflows, thus there are two
subsections, Creating full files from “run_agmip_simple_delta.R” outputs and Creating full files
from “run_agmip_simple_mandv.R” outputs, describing how to use this run script.

Creating “full” files from “run_agmip_simple_delta.R” outputs

After running “run_agmip_simple_delta.R” you will have a series of basic delta adjusted
.AgMIP files located in “~/R/data/Climate/Simplescenario/”. These new AgMIP files contain
adjusted data for temperature maximum (Tmax), temperature minimum (Tmin) and precipitation
(Rain) as well as the baseline data for solar radiation (Srad).

If you require the full delta adjusted .AgMIP files with wind speed (Wind), dew point (Dewp),
vapor pressure (Vprs), and the relative humidity (Rhum), you will have to run the script
“run_agmip_simple2full.R”. This run script will paste the baseline values for Wind and Rhum
and will calculate new values for Dewp and Vprs using relative humidity controlled vapor
pressure based on daily Tmax..

IMPORTANT: The script, “run_agmip_simple2full.R”, uses the outputs from

“run_agmip_simple_delta.R” to create the full delta adjusted .AgMIP files. Thus
“run_agmip_simple_delta.R” must be run prior to “run_agmip_simple2full.R” for the
script to function correctly.

To run this script,

1. Open R and then open the run script “run_agmip_simple2full.R” to edit the input
variables. You could also edit the run script in a text editor if you prefer.
2. Change the rootDir to reflect the location of the folder “~/R”.
3. Save the updated run script as your template “run_agmip_simple2full.R” script.
 Suggested workflows for the AgMIP Climate run scripts - 38

Adjust the input variables basefile and end.code to reflect the relevant information of
your baseline AgMIP file. For AgMIP files produced by “run_agmip_simple_delta.R”,
the variable end.code should be defined as “XA” unless you have made other
downscaling adjustments to the files. You should also adjust the variables run.gcms,
run.rcps, and run.decsrun.decs to run a subset of these input variables based on the files
you produced by “run_agmip_simple_delta.R” and the files for which you require a full
climate dataset.
4. Save the amended script with a unique name (e.g. “run_agmip_simple2full_1.R” or
“run_agmip_simple2full_deltas.R”) to “`/R/r/”.
5. Confirm the presence of your basefile in “~/R/data/Climate/Historical/” as well as the
simple files to be converted in “~/R/data/Climate/Simplescenario/”.
6. Source (run) the script from the R Console
7. Try not to use your computer if possible to improve run time of script.
8. After the script has completed, the basic delta adjusted files should be located in
~\\R\\data\\Climate\\Fullscenario\\. Confirm the presence of these files.

If you chose to run “run_agmip_simple_delta.R” and “run_agmip_simple2full.R” with the test

file, “USAM0XXX.AgMIP” to produce the full future scenario files in .AgMIP format, you can
check the first created file “USAMCAXA.AgMIP”, against the data shown in Appendix 3.

Creating “full” files from “run_agmip_simple_mandv.R” outputs

If you require that the mean and variability change is also applied dew point (Dewp) and vapor
pressure (Vprs), the run script “run_agmip_simple2full.R” can be used to expand these files.
The script “run_agmip_simple2full.R” has been updated for version 2.0 of the Guide to use the
files produced by “run_agmip_simple_mandv.R” (found in “~/R/data/Climate/Simplescenario”).
The run script calculates new daily values for Dewp, and Vprs based on the baseline relative
humidity (Rhum) and the newly calculated temperature maximum (Tmax). The run script
produces new “full” files located in “~/R/data/Climate/Fullscenario”.

To run this script and convert the simple files to full,

1. Open R and then open the run script “run_agmip_simple2full.R” to edit the input
variables. You could also edit the run script in a text editor if you prefer.
2. Change the rootDir to reflect the location of the folder “~/R”.
3. Save the updated run script as your template “run_agmip_simple2full.R” script.
Adjust the input variables basefile, and end.code to reflect the relevant information of
your baseline AgMIP file. For AgMIP files produced by “run_agmip_simple_mandv.R”,
 Next Steps… - 39

the variable end.code should be defined as “XF” where “X” denotes “no additional
downscaling” and “F” denotes “Mean and daily variability change for Tmax, Tmin, and
P”. If you have made additional downscaling adjustments to your AgMIP files to be
converted, adjust end.code accordingly. You can also adjust run.gcms, run.rcps, and
run.decsrun.decs to run a subset of these input variables based on the files you produced
by “run_agmip_simple_delta.R” and the files for which you require a full climate dataset.
4. Also, you should change the headerplus information to read “<your site location,
country> with mean and daily variability changes for Tmax, Tmin and P”
5. Save the amended script with a unique name (e.g. “run_agmip_simple2full_2.R” or
“run_agmip_simple2full_mandv_1.R”) to “`/R/r/”.
6. Confirm the presence of your basefile in “~/R/data/Climate/Historical/” as well as the
simple files to be converted in “~/R/data/Climate/Simplescenario/”.
7. Source (run) the script from the R Console
8. Try not to use your computer if possible to improve run time of script.
9. After the script has completed, the basic delta adjusted files should be located in
~\\R\\data\\Climate\\Fullscenario\\. Confirm the presence of these files.

Next Steps…

This concludes Version 2.0 of the Guide for Running AgMIP-Climate Scenario Generation
Tools with R in Windows. We will be expanding this guide in the future to include other climate
scenario tools. Your feedback is helpful and we appreciate any suggestions or recommendations
you may have to improve this guide.

If you have further questions, contact please feel free to contact Nicholas Hudson at
[email protected].

Thanks again for your collaboration and good luck with R!

 Appendix 1: Creating .AgMIP files in Excel - 40

Appendix 1: Creating .AgMIP files in Excel

This appendix describes how to create .AgMIP files in Excel manually without use of “AgMIP
Excel File Template_v2.0.xls”.

Here's the general approach:

1) Arrange data series in excel spreadsheet with proper column order, proper units, etc. Missing
values should be filled with -99 (you can get RHUM and wind speed from the MERRA-based
dataset I provided if you do not have these, but Tdew and VPRS will need additional conversion
and can be left as missing for the purposes of the R routines described in this Guide.

2) Highlight all of the four columns that indicate date: @DATE, YYYY, MM, and DD (e.g.,
their first entries are "1980001 1980 1 1"), right click, and select "format cells". Select the
number category and then change the number of Decimal places to 0.

3) Highlight the columns corresponding to SRAD, TMAX, TMIN, RAIN, WIND, DEWP, and
VPRS, right click, and select "format cells". Select the number category and then change the
number of Decimal places to 1.

4) Highlight the column corresponding to RHUM, right click, and select "format cells". Select
the number category and then change the number of Decimal places to 0.

5) Right-click on the column letter at the top of the excel spreadsheet for the @DATE column
(e.g., the "A" for Column A), select "Column Width" and set the column width to 7.

6) Right-click on the column letter at the top of the excel spreadsheet for the YYYY column
(e.g., the "B" for Column B), select "Column width", and set the column width to 6.

7) Right-click on the column letter at the top of the excel spreadsheet for the MM and DD
columns ("C" and "D"), select "Column width", and set the column width to 4.

8) Right-click on the column letter at the top of the excel spreadsheet for the remaining columns
(SRAD to RHUM; "E" to "L"), select "Column width", and set the column width to 6.

9) Select "Save as" from the file menu and save as type "Formatted Text (Space
Delimited)". Type in a full name with the extension (e.g., "USNY0XXX.AgMIP").
 Appendix 1: Creating .AgMIP files in Excel - 41

10) You may need to click yes on a dialog box asking if you want to save only this sheet, and
after you click that you can cancel any other dialog boxes or separate save as screens that may
appear.

11) Open the .AgMIP file in notepad and then copy 5-line header from a different existing
.AgMIP file and paste it on top of the AgMIP file you just created. Modify header as necessary
(e.g., header, 4-letter code, latitude, longitude, elevation). TAV is the average of all Tmax and
Tmin in the dataset, and AMP is half of the difference between the warmest average monthly
temperature and the coolest average monthly temperature averaged over the entire dataset.
REFHT is the height of the thermometer and WNDHT is the height of the anemometer (put -99
if unknown).

12) Save the file to record these modifications.

 Appendix 2: Example file for “agmip_farmclimate.R” - 42

Appendix 2: Example file for “agmip_farmclimate.R”

Below is an example output data file created by “run_agmip_farmclimate.R” and located in

“~\\R\\data\\Climate\\Historical\\”. This data file is provided so that you can confirm that your
script ran correctly. The first 32 days of the data have been provided below as well as the last 5
days of the data set (December 27-31, 2010).

*WEATHER DATA : Embu, Kenya, cast to site 01 using WorldClim-derived climatological differences

@ INSI LAT LONG ELEV TAV AMP REFHT WNDHT

MB01 -0.700 37.540 1097 20.4 2.0 -99.0 -99.0
@DATE YYYY MM DD SRAD TMAX TMIN RAIN WIND DEWP VPRS RHUM
1980001 1980 1 1 23.0 24.4 12.6 0.0 238.4 18.0 20.9 67
1980002 1980 1 2 23.8 27.1 12.1 0.0 202.7 19.6 23.1 63
1980003 1980 1 3 21.5 25.3 10.1 0.0 234.7 16.0 18.3 56
1980004 1980 1 4 23.9 26.2 12.3 0.0 220.0 15.9 18.2 52
1980005 1980 1 5 24.3 29.7 13.7 0.0 197.3 21.8 26.5 62
1980006 1980 1 6 23.1 25.9 12.1 0.0 163.4 17.7 20.4 60
1980007 1980 1 7 23.2 27.6 10.3 0.0 173.3 18.7 21.8 58
1980008 1980 1 8 24.4 27.6 12.9 0.0 213.5 16.9 19.4 51
1980009 1980 1 9 21.8 25.6 12.9 0.0 181.7 16.2 18.6 56
1980010 1980 1 10 23.8 26.7 12.5 0.0 104.6 14.7 16.9 47
1980011 1980 1 11 23.5 28.2 12.2 0.0 186.3 16.5 18.9 48
1980012 1980 1 12 19.9 25.9 14.1 0.0 199.3 15.3 17.5 51
1980013 1980 1 13 22.7 25.9 13.1 0.0 196.4 15.6 17.9 52
1980014 1980 1 14 22.4 26.2 11.6 0.0 212.4 16.5 18.9 54
1980015 1980 1 15 22.4 27.5 12.7 0.0 254.4 17.4 20.1 54
1980016 1980 1 16 20.2 25.9 15.1 0.0 179.7 17.1 19.7 58
1980017 1980 1 17 23.6 25.9 12.6 0.0 255.5 16.8 19.3 57
1980018 1980 1 18 21.3 27.1 13.3 0.0 183.0 16.8 19.2 52
1980019 1980 1 19 23.2 27.2 13.6 0.0 187.3 15.6 17.8 48
1980020 1980 1 20 24.1 27.8 11.6 0.0 237.0 17.1 19.7 51
1980021 1980 1 21 23.3 28.1 12.7 0.0 281.5 15.3 17.6 45
1980022 1980 1 22 23.6 27.1 13.1 0.0 247.3 16.1 18.5 50
1980023 1980 1 23 22.7 27.6 14.6 0.0 188.2 13.8 15.9 42
1980024 1980 1 24 21.0 29.5 14.5 0.0 146.4 16.6 19.1 45
1980025 1980 1 25 22.2 28.3 15.4 0.7 107.6 17.2 19.9 50
1980026 1980 1 26 22.1 25.2 18.1 0.3 118.5 16.7 19.2 59
1980027 1980 1 27 19.5 25.5 15.0 0.0 155.6 20.9 25.1 76
1980028 1980 1 28 3.5 25.9 16.1 0.0 148.9 19.7 23.3 68
1980029 1980 1 29 18.4 26.5 14.6 0.0 136.2 14.9 17.1 48
1980030 1980 1 30 3.1 25.8 18.1 0.0 102.9 15.2 17.4 51
1980031 1980 1 31 2.9 26.8 16.7 5.4 127.4 16.8 19.3 54
1980032 1980 2 1 20.0 26.0 16.1 0.0 150.4 17.5 20.2 59
…
2010361 2010 12 27 18.7 26.0 17.3 5.8 77.5 16.2 18.5 54
2010362 2010 12 28 24.0 24.2 16.7 2.5 71.1 15.8 18.1 59
2010363 2010 12 29 20.1 26.0 15.0 0.0 75.4 14.4 16.5 48
2010364 2010 12 30 19.8 25.6 13.9 0.0 78.8 15.5 17.7 53
2010365 2010 12 31 23.7 26.2 14.3 0.0 70.7 13.2 15.3 44
 Appendix 3: Example file for “agmip_simple_delta.R” and “agmip_simple2full.R” - 43

Appendix 3: Example file for “agmip_simple_delta.R” and

“agmip_simple2full.R”

Below is the data from “USAMCAXA.AgMIP”, the first file that is created by
“run_agmip_simple_delta.R” and “run_agmip_simple2full.R” located in
“~\\R\\data\\Climate\\Fullscenario\\”. This data file is provided so that you can confirm that your
script ran correctly. The first 32 days of the data have been provided below as well as the last 5
days of the data set (December 27-31, 2010).

*WEATHER DATA : USAMCAXA - baseline dates maintained for leap year consistency

@ INSI LAT LONG ELEV TAV AMP REFHT WNDHT

USAM 42.017 -93.750 329 11.2 14.6 -99.0 -99.0
@DATE YYYY MM DD SRAD TMAX TMIN RAIN WIND DEWP VPRS RHUM
1980001 1980 1 1 1.2 1.3 -1.5 0.0 3.1 -0.3 6.0 89
1980002 1980 1 2 4.7 -0.3 -2.6 0.0 4.9 -7.6 3.5 58
1980003 1980 1 3 1.9 -0.3 -4.8 0.0 4.3 -9.0 3.1 52
1980004 1980 1 4 3.8 0.2 -2.6 0.0 4.1 -5.2 4.2 67
1980005 1980 1 5 1.0 0.2 -3.2 1.5 3.4 -2.5 5.1 82
1980006 1980 1 6 8.5 1.9 -7.0 2.1 9.1 -0.8 5.7 82
1980007 1980 1 7 6.7 -6.4 -15.9 0.0 8.2 -13.4 2.2 58
1980008 1980 1 8 6.7 -8.7 -16.5 0.0 2.9 -17.1 1.6 51
1980009 1980 1 9 2.2 -11.4 -20.4 1.5 3.7 -16.2 1.8 68
1980010 1980 1 10 8.0 6.3 -13.7 0.0 8.0 5.3 8.9 93
1980011 1980 1 11 4.0 11.3 -9.8 0.0 11.9 7.3 10.2 76
1980012 1980 1 12 8.6 0.8 -13.7 0.0 6.1 -10.4 2.8 43
1980013 1980 1 13 8.6 12.5 1.3 0.0 6.7 2.4 7.3 50
1980014 1980 1 14 2.1 6.9 -3.2 0.0 4.1 -1.0 5.7 57
1980015 1980 1 15 1.0 8.6 4.6 0.0 4.1 7.2 10.2 91
1980016 1980 1 16 1.9 7.5 2.4 24.4 5.6 7.4 10.3 99
1980017 1980 1 17 3.7 2.5 -2.6 1.2 5.6 -0.6 5.9 80
1980018 1980 1 18 1.4 1.3 -3.2 0.0 2.7 1.2 6.6 99
1980019 1980 1 19 1.3 1.3 -4.3 2.1 4.3 -0.0 6.1 91
1980020 1980 1 20 3.1 1.3 -8.2 0.0 2.1 -6.1 3.9 58
1980021 1980 1 21 10.4 1.3 -7.0 0.0 4.2 -0.0 6.1 91
1980022 1980 1 22 8.8 1.9 -5.4 0.0 8.2 -1.2 5.6 80
1980023 1980 1 23 2.9 -4.2 -10.9 0.0 4.0 -13.4 2.2 49
1980024 1980 1 24 5.0 6.9 -7.0 0.0 5.7 3.9 8.1 81
1980025 1980 1 25 6.9 5.8 -4.8 0.0 5.9 3.5 7.8 85
1980026 1980 1 26 7.5 -4.2 -14.3 0.0 6.1 -11.5 2.6 57
1980027 1980 1 27 5.9 -9.8 -13.2 0.0 4.5 -16.2 1.8 60
1980028 1980 1 28 9.0 -8.7 -12.6 0.0 4.6 -14.7 2.0 62
1980029 1980 1 29 4.8 -9.2 -16.5 0.0 3.8 -14.6 2.0 65
1980030 1980 1 30 12.7 -9.8 -12.6 1.5 4.7 -12.6 2.3 80
1980031 1980 1 31 4.7 -10.9 -19.8 0.0 3.8 -13.2 2.2 83
1980032 1980 2 1 6.7 -8.5 -22.8 0.0 3.0 -11.4 2.6 80
…
2010361 2010 12 27 3.5 1.1 -0.3 0.0 2.0 -0.8 5.8 87
2010362 2010 12 28 4.8 1.7 -0.1 9.0 1.4 -0.7 5.8 84
2010363 2010 12 29 3.3 2.8 1.5 2.8 4.2 1.8 7.0 93
2010364 2010 12 30 2.6 4.0 1.7 0.0 5.1 2.0 7.1 87
2010365 2010 12 31 3.4 1.3 -1.5 0.9 5.3 -2.5 5.1 76