CLIMATE ANALOGUES_2.0 R PACKAGE

INSTALLATION AND USER GUIDE

David Arango1,2, ,Edward Jones1,2, Julian Ramirez-Villegas1,2,3, Osana Bonilla1,2, Andy Jarvis1,2.

1CGIAR Research Program on Climate Change, Agriculture and Food Security (CCAFS); 2International Center for Tropical Agriculture (CIAT), Cali, Colombia; 3School of Earth and

Environment, University of Leeds, Leeds, UK.

July 2014

TABLE OF CONTENTS

Installation

1. Install R

2. Install R Studio

3. Open run_analogues.R

4. Installing packages and GTK+

User Guide

Basic run

Farms of the Future (FOTF) run

Soil module (and other variables)

Button functions

Troubleshooting guide

More information and resources

Appendix

1. Analogue site identification

INSTALLATION

1. Install R

R is a software programming language and environment for statistical computing and graphics.

a) If you have internet connection: download and install the relevant R software from

http://cran.r-project.org/.

OR

b) If you are in an Analogues tutorial without internet connection: open the folder

“/Analogues_GUI/R and Analogues install/Install for Windows”, from this folder run “R-

3.1.0-win.exe” (Fig. 1), and follow the prompts to install R.

2. Install R Studio

R Studio is free and open source interface that facilitates development in R.

a) If you have internet connection: download and install the relevant R software from

http://www.rstudio.com/products/rstudio/download/.

OR

b) If you are in an Analogues tutorial without internet connection: open the folder

“/Analogues_GUI/R and Analogues install/Install for Windows”, from this folder run

“RStudio-0.98.953.exe” (Fig. 1), and follow the prompts to install R Studio.

Figure 1 Screenshot showing the location of the R and R Studio executable files used for installing the Analogues R package when internet limitations are present.

3. Open run_analogues.R

Now that R and R Studio have been installed we may open our script to finish the installation.

To do this open the file “/Analogues_GUI/run_analogues.R” using R Studio. Figure 2 depicts

how the run_analogues.R file should appear when opened in R Studio.

Figure 2 Screenshot of the run_analogues.R file opened in R Studio.

4. Installing packages and GTK+

The run_analogues.R file is used to install the required R packages (needs to be performed once

only), as well as to launch the interface. We must first change the working directory so that the

R script knows where to locate the data and save the results; many of the options in the

interface are loading dynamically and will automatically change depending on the data you

have located on your computer. Follow these steps to install the packages:

1. Change the directory on line #23 to identify the Analogues_GUI folder on your

computer, e.g. setwd("D:/eg_directory/Analogues_GUI/"). Remember that R requires

all “\” to be changed to “/” to locate the folder correctly.

2. To execute the line highlight it and press ctrl + enter, or use the “Run” button at the top

right of the input module. No red error messages should be seen.

3. Save the file by pressing ctrl + s (your working directory will be saved and you will not

have to change it next time).

4. To load all of the required packages remove the “#” from the front of line #26 and

execute that line. A message should be seen indicating successful installation of the

packages (Fig. 3).

If the message above is seen then you may replace the “#” at the start of line #26 as the

packages only need to be installed once. If error warnings are shown please check your

working directory on line #23 is correct before installing the packages again.

5. Execute line #29 require(Analogues). This line loads all of the required packages, thus

making the prewritten scripts and functions available for use (Fig. 4).

REMEMBER: To execute a line in R Studio highlight the entire line and press ctrl + enter or use the “Run” button. Also, when changing the working directory change all “\” to “/”.

Figure 3 Message shown on correct installation of packages.

Figure 4 Message shown when Analogues_2.0 package is activated (required).

6. Execute line #30 Load_GUI() t the interface. You will be prompted to install a toolkit for

creating graphical user interfaces (GUIs) called GTK+ (Fig. 5). Select OK to install the

toolkit.

The GTK+ toolkit will download and install automatically and the GUI will appear (Fig. 6).

Figure 6 A successfully launched Climate Analogues graphical user interface (GUI).

AN INTERNET CONNECTION IS NEEDED TO INSTALL GTK+, however following installation Climate Analogues will operate completely independent of the internet.

Figure 5 Messages identifying that GTK+ is not present on the computer and that it must be installed.

USER GUIDE

Now that installation is complete we may begin using the Climate Analogues GUI to run the

calculations. There are two options to choose from Basic or Farms of the Future (FOTF) run. In

basic runs you may choose to compare any individual climate model, meanwhile for FOTF runs

all of the models are run to capture the variability between the models and provide a more in-

depth analysis.

Launch the GUI

Once installation is complete, the Climate Analogues GUI may be launched by simply running

lines #23 – 30 (Fig. 7). Remember to put “#” in front of line #26 so that the packages are not

reinstalled.

Basic run

Farms of the Future (FOTF) run

Soil module (and other variables)

Using the Climate Analogues interface

Double click Run_analogues.R (/Analogues tool interface Kenya/Run_analogues.R)

Run line 22 to set your working directory (you should not need to change the directory again if

you save it from the installation process)

Run line 25 to launch the interface

Figure 7 The lines that need to be executed to launch the Climate Analogues GUI.

Select tab 1A to perform a basic run or tab 2A to perform a Farms of the Future (FOTF) run.

Note: help messages are shown in the status bar at the bottom of the interface which also

indicates calculations are occurring and estimate remaining time for FOTF runs.

Enter parameters and click “Run”. The defaults of both runs are set to the most commonly used

parameters so to perform your first run you may only need to change the site name and

coordinates.

Wait for run to finish before proceeding to the results page or you may accidently load results

from previous runs. Further, only one run may be performed at a time

Once a run is complete proceed to the relevant tab, 1B or 2B, to view the results, apply

thresholds and agreements and select analogue sites.

You may select a shapefile to project national, state or district boundaries and zoom to specific

areas when selecting analogue sites. I have given you shapefiles in the “/Analogues tool

interface Kenya/Data/ken_adm” folder. Select KEN_adm0.shp for country, KEN_adm1.shp for

state or KEN_adm2.shp for district boundaries. Note any shapefile may be projected on the

results map, but to use the zoom functions the shapefile must be downloaded from:

http://www.diva-gis.org/gdata due to the coding we have used in this function.

When selecting analogue sites to investigate their raw data you have the two options of:

“Selecting analogue from map” which allows you to click on an output map to extract the data;

or if you prefer you may first export the maps to GIS or GoogleEarth software to identify sites of

interest then return to the user interface and use the “Select analogues from coordinates

option”. If you select the coordinates option you will need to perform the analysis as normal up

to this stage, then the map to use may be found in the “/Analogues tool interface

Kenya/Data/out” folder as: site name_selected direction_ threshold.tif for basic runs; or

FOTF_agreement_site name.tif for FOTF runs.

The user interface does not include a function to clear output similarity maps so you may need

to clear the contents of the “/Analogues tool interface Kenya/Data/out” folder periodically.

Additional information:

Do not enlarge the viewing windows that maps are projected on as this will move the projected

shapefile and points

Data used to produce graphs is printed in the R studio window. If you would like to export it as

a table: highlight the table and copy it into excel.

DO NOT CUT CORNERS. When you perform a new run you must follow the steps through on the

results tab one by one to ensure that the right data is being used and the correct raw data and

similarity maps are being used.

Keep the R studio page visible so you can see any warning messages that show if calculation has

failed.

Be careful that parameters are correctly set before you perform a FOTF or plot raw data. FOTF

calculations take a long time to process and cannot be stopped unless you shut down the

interface and R studio.

If you only want to use one variable set the weight of the other variable to zero.

Approximate time of lengthy procedures for Kenya:

Basic run: 30 sec

FOTF run: 7-8 min

Extract raw data for FOTF: 1-2 min

When you are finished click “Clear all graphs” to erase all graphs before closing the interface.

For now analysis is limited to scenario “A1B” and time period “2020_2049” further functionality

will be added to the tool in the future.

BUTTON FUNCTIONS

Basic run:

RUN:

Create new folder/deletes existing folder and results (//wd/Data/out/site_name_direction/)

load parameters, perform run, write results as TIFF and KML

(//wd/Data/out/site_name_direction/site_name_direction.tif)

(//wd/Data/out/site_name_direction/site_name_direction.kml)

extract tmean and prec data, plot, print data in console, save csv

(//wd/Data/out/site_name_direction/ ref_basic_tmean_or_prec.csv)

Plot raw results:

Plots raw climatic similarity

Apply threshold:

Restricts raw results to the defined highest quantile. Eg. 0.95 displays the top 5% of sites.

write results as TIFF and KML

(//wd/Data/out/site_name_direction/site_name_direction_threshold.tif)

(//wd/Data/out/site_name_direction/site_name_direction_threshold.kml)

Select analogue sites:

Facilitates visualisation and comparison of data (tmean and prec) from the reference site to the

selected analogue site by extracting and plotting the data.

Sites may be selected directly off the map (with a zoom option to state and district level if sites

are downloaded from DIVA-GIS or to country level if using …2008)

Reference site and analogues tmean and prec data is printed in the console as well as

coordinates

TROUBLESHOOTING GUIDE

This troubleshooting guide describes common issues and how to correct them.

Shapefile not found: delete files

Various errors, user-interface screen remains grey and will not return to interactive stage.

An error has occurred. Run line #33

enabled(.win)=T to return the window to the interactive stage and check all input data is

correct before rerunning the analysis.

Trying to use soil module when correct data is not present:

Make sure data is in the correct folder and the extent and resolution of the data is the same as

the input climate data.

MORE INFORMATION AND RESOURCES

CCAFS has developed a Climate Analogues homepage and blog where you can find all of the

information behind the Climate Analogues approach and resources on using the online tool and

the R package (http://www.ccafs-analogues.org). Blog topics include updates on all Climate

Analogues activities such as Farms of the Future projects and case studies, training workshops,

as well as general news on tool applications and tool improvements.

APPENDIX

1. Analogue site identification This essential information is required by the CCAFS Climate Analogues team for the

identification of analogue sites:

Essential information required for analogue site identification

Country name

Village name

Village longitude (dd)

Village latitude (dd)

Search area within which to look for analogue sites e.g within

same country, within a selection of countries or globally.

Climate variables i.e. the default of monthly mean temperature

and precipitation, or bioclimatic variables

Growing season(s) of interest. e.g. all year or May to October only

Identification of analogue sites performed by the CCAFS Climate Analogues team:

1. Using the data provided in the Essential Information table above the future climatic

conditions at the reference site are plotted for all available GCMs and visually inspected.

Outliers are removed from further analysis.

2. Analogue runs are performed using the Analogues R package for all remaining GCMs

using the parameters given in the Essential Data table. The default future conditions are

calculated as the average of the 2020 to 2049 time period under emissions scenario

A1B. The effect of data rotation may be investigated, as well as the effect of using the

given variables in combination or individually to elucidate their individual influence on

the results.

3. The top 10% most similar sites for each GCM are extracted and compiled to produce a

single map describing GCM agreement on analogue sites e.g ≥5 or ≥10 GCM agreement.

4. The raw data of sites located within the identified analogue areas should be investigated

to ensure that climatic conditions are sufficiently similar to projected future conditions

at the reference site.

5. The resultant identified analogue areas may be further reduced by considering soil

properties and available infrastructure such as distance to major roads, markets, rivers,

irrigation availability, etc.