#-----------------------------------------# 
# The following document is intended to 
# guide users in the use of GRIP 2.0.
# GRIP 2.0 (Generating random input parameters)
# 


#-----------------------------------------# 
#---GRIP 2.0: Major steps-----------------#
#-----------------------------------------#

# GRIP 2.0: generates random sets of
#	input parameters in the following major steps:

# 1. The program READS IN the following files 
#	(A) RAMAS Spatial 5.0/6.0 PVA model (*.ptc file), 
#   (B) RAMAS Metapop file (*.mp), 
#	(C) a habitat suitability map (*.asc), 
#	(D) and a patch ID map (*.asc). 
# The first two files ((A): *.ptc and (B) *.mp) 
#	require certain configurations. 
# See section 'Prior to running GRIP 2.0'.
		
# 2. Spatial parameters are varied on 
	# the habitat suitability (raster) map
	# and a modified version of RAMAS Spatial file 
	# is created. The two outputs at this stage include:
	# (1) 'ptc_*.ptc' (generic file name), and
	# (2) 'HSmap_*.asc'
# One file is created for each of the '*' replicate simulations. 
# Parameters varied during this stage include:
	# spatial parameters: number of populations 
	#(we use the terms population and patches synonymously), 
	# habitat suitability values, habitat suitability
	# threshold, neighbourhood distance, 
	# method for calculating distances between patches. 
# The majority of these parameters are varied 
	# directly on raster-based habitat suitability map.
# A new habitat suitability map is created 
	# (based on the varied parameters), which is 
	# used to define the new metapopulation structure. 
# Each replicate RAMAS Spatial Data file (ptc_*.ptc) 
	# is run in RAMAS Spatial 6.0 using a 
	# batch file created by GRIP 2.0. 
# Results from runs of each replicate file are 
	# recorded, saved, and collated into two tables, 
	# "PTCvariables.txt" and "spatialvar.txt".
# Results include: total amount of habitat, 
	# mean patch size, average patch quality, 
	# number of populations, mean core area, 
	# mean edge to area ratio, mean patch edge, 
	# mean shape index, and percent area habitat 
	# within the landscape.
# The GRIP 2.0 code can be customized by the 
	# user to collate additional variables of interest.
      
# 3. A 'pref_metapop' file is created, 
	# which is created from the output 
	# from the previously run ptc_*.ptc file 
	# (called pref_*.mp, one is created for each 
	# of the n replicate simulations). 
	# This is created by GRIP 2.0 because 
	# a copy of the metapop file is not created 
	# automatically when RAMAS Spatial models 
	# are run using batch files. Because GRIP 2.0 
	# uses output from the RAMAS Spatial Data 
	# program and the user-specified Metapop Link 
	# file, users must ensure that parameters 
	# specified in the original Metapop Link 
	# file (*.mp) are specified the same way in the 
	# RAMAS GIS model (*.ptc). 
	# See more details on ensuring consistency 
	# between the two files below.
    
# 4. A 'prefile' file is created, which 
	# is an interim replicate simulation file 
	# (called interim_*.mp, one is created 
	# for each of the n replicate simulations). 
	# Key steps during the 'prefile' creation 
	# stage of GRIP 2.0 include varying
	# parameters such as initial abundances and Rmax. 
	# In addition, a population with an arbitrarily 
	# low K is added to simulate dispersal survival 
	# (see Curtis and Naujokaitis-Lewis 2008).
		
# 5. A 'repfile' file is created, which is 
	# a final replicate simulation file to be run 
	# during the RAMAS Metapop simulations 
	# (called rep_*.mp, one is created for 
	# each of the n replicate simulations). 
	# Key steps at this stage of GRIP 2.0 include 
	# varying parameters including: frequency, 
	# intensity and spatial extent of catastrophes, 
	# dispersal rates, number of population pairs 
	# connected by dispersal, correlations in 
	# vital rates, and vital rates. 
	# See Curtis and Naujokaitis-Lewis 2008 for details.
  
# 6. All rep_*.mp files are run in 
	# RAMAS Metapop using a batch file 
	# created by GRIP 2.0. 
	# Results from each of the n repfiles 
	# are recorded, saved, and collated into one table 
	# (data.csv) for further analysis.



#------------------------------------------#
# File prep: TO DO BEFORE running GRIP 2.0 #
#------------------------------------------#

# RAMAS GIS has several modules accessible 
	# from the RAMAS GIS "shell" window, including 
	# Spatial Data, and Metapopulation Model 
	
# Prior to running GRIP 2.0, the following 
# 2 files require preparation :
	# 1. RAMAS GIS Metapop file ( *.mp, also 
	# called RAMAS METAPOP "LINK" FILE)
	# 2. RAMAS GIS Spatial Data file (*.ptc )

#-----------------------------------------# 
# A. RAMAS Metapop Program Overview 
	# and Input File Preparation
#-----------------------------------------# 

#----RAMAS METAPOP "LINK" FILE------------#

# A default RAMAS Metapop file (*.mp) 
	# is used to specify parameters that are not 
	# calculated by the RAMAS Spatial Data program, 
	# but required for simulations and 
	# model sensitivity analysis.
# This *.mp file is used as the link to 
	# the metapopulation model in the 
	# RAMAS GIS Spatial Data program.
	# see Model Menu in Spatial Data program for details.
# To specify a *.mp file as the default 
	# RAMAS Metapop link file, click on the 
	# General Information drop-down menu of 
	# the RAMAS GIS Spatial Data program, 
	# then click on 'Link To Metapopulation" 
	# and select the *.mp model input file 
	# in the browser box next to 'Other data from'.
# Users should ensure that they have read 
	# the instructions for creating and 
	# running RAMAS Spatial and RAMAS Metapop files. 
# Although the Metapop Link file may 
	# include more than 1 population, for some 
	# parameters only values associated with 
	# the 1st population will be read by 
	# the RAMAS Spatial Data module. 
# In other cases, for instance when K or 
	# Initial Abundances are not specified 
	# as a function of habitat, users will 
	# need to specify parameters for 
	# all populations in the Metapop Link file. 
	# GRIP 2.0 will use the values of K or Initial Abundances from the Metapop Link file to sample values 
	# for new populations (habitat patches).
# Users should ensure that the Metapop Link (*.mp) 
	# file settings are consistent with those 
	# in the RAMAS Spatial Data file (*.ptc). 
	# This includes parameters related to 
	# catastrophes and density dependence. 
	# GRIP 2.0 requires such consistency to 
	# write the final Metapop file correctly; 
	# this file is created by GRIP 2.0 after the 
	# Spatial data (*.ptc) replicate file is 
	# created and run. For example, if a catastrophe 
	# is Regional in extent, this parameter and 
	# all associated parameters are specified 
	# in the Metapop Link file. 
	# If a catastrophe is Local in extent, 
	# this parameter and all associated parameters 
	# are specified in both the Metapop Link 
	# file and the Spatial Data program. 


#------------------------------------#
# Check parameters in RAMAS Metapop 
	# and RAMAS Spatial:
#------------------------------------#

# 1. Specify whether or not 1 or 2 
	# local catastrophes are modelled 
	# (i.e. local catastrophe probabilities)
	# in both RAMAS Spatial Data program and 
	# RAMAS Metapop
# 2. If 1 or 2 local catastrophes are modeled, 
	# specify the local catastrophe multipliers in 
	# both RAMAS Spatial Data program and RAMAS Metapop
# 3. Specify the spatial extent of any 
	# catastrophe in RAMAS Metapop
# 4. Specify Rmax, relative fecundity, and 
	# relative survival in both RAMAS Spatial Data 
	# program and RAMAS Metapop
# 5. Specify dispersal and correlation distance 
	# function parameters in both RAMAS Spatial Data 
	# program and RAMAS Metapop
		

#------------------------------------#
# Check parameters specific to 
	# RAMAS Metapop:
#------------------------------------#
	
# In the current version of RAMAS GIS (6.0) 
	# Once Spatial Data module is run, a Metapop (mp file) 
	# is produced. However, the Metapop file must be 
	# exported and saved manually using the GUI. 
# Therefore users must ensure the following inputs 
	# are specified in the Metapop file (*.mp) 
	# as these inputs will be used to write the Metapop file # correctly for use in the Metapop program:
	# 1. Number of stochastic runs
	# 2. Specify the time horizon 
	#(i.e. number of time steps in the simulation)
	# 3. Specify the unit of each time step 
	# 4. Specify at least one stage matrix of survival 
	# and fecundity parameters and at least 
	# one standard deviation matrix. 
                
    # Note that if more than 1 stage and standard deviation 
	# matrices are specified in the Metapop Link (*.mp) 
	# file, the stage and standard deviation matrices 
	# of population 1 are used as the default 
	# stage matrix for all populations in the 
	# Spatial Data module. However, the additional 
	# stage and standard deviation matrices are 
	# recorded in the Metapop Link file so it 
    # would be possible for users to customize the 
	# GRIP 2.0 code so that populations are attributed 
    # different stage matrices when the final 
	# RAMAS Metapop input files are created for the 
    # replicate simulations and sensitivity analysis 
	# (i.e. Step 5, below). Some code for this has already 
    # been incorporated into GRIP 1 (see Curtis and
	# Naujokaitis-Lewis 2008, Ecological Applications) 
	 
# 5. Specify the initial age/stage distribution 
	# (in other words the age or stage structure 
	# of the population). As instructed in 
	# the RAMAS GIS manual: "One of the 
	# parameters taken from [the *.mp] file 
	# (Metapop Link) is the distribution of 
	# the initial abundance to stages or 
	# age classes. To specify the age or stage distribution,
	# open [the Metapop Link] file in RAMAS Metapop, 
	# enter a large [arbitrary] number in the Initial 
	# abundance (in the Populations dialog) 
	# for the first population (other populations in 
	# this file are ignored by the Spatial data program), 
	# and specify the distribution of this initial 
	# abundance to stages in the Initial abundances 
	# dialog.  The reason for entering a large number 
	# as the total initial abundance is to minimize 
	# variation due to rounding when populations of 
	# different sizes are assigned to the same 
	# distribution of total abundance to stages." (Akçakaya 2005)
	 
# 6. Specify which types of stochasticity or errors 
	# are modeled and any associated parameters 
	# (i.e. demograpic, environmental, sampling error, etc) 
	 
# 7. Catastrophe parameters (probabilities, multipliers, 	
	# spatial extent, correlation among 2 catastrophes, etc)

# 8. Density dependence parameters: note that the 
	# model of density dependence should always be 
	# population specific for use with GRIP 2.0 (see Density Dependence under the Model menu of the Metapopulation 
	# model module (i.e. RAMAS Metapop). 
	# The current version of GRIP 2.0 does not 
	# contain code to accept models using user-defined 
	# models of density dependence. However, the code 
	# could be customized for this purpose by the user.
   	
# It is possible that a RAMAS Metapop model 
	# may not model catastrophes yet may still have 
	# a parameter that the catastrophes affect selected. 
	# For GRIP 1 or GRIP 2 to run properly, no
	# catastrophe-related parameters must be 
	# selected if catastrophes are not actually modeled. 
	# In such cases, verify that the PVA model input 
	# file has not selected catastrophe parameters: 
		# Open the *.mp input file in RAMAS Metapop 5.0. 
		# Check the RAMAS Metapop 5.0 input file to 
		# ensure that no parameters affected by 
		# catastrophes have been highlighted.  
		# If none are highlighted, catastrophes are 
		# not modeled (through this option).
		# If yes, check to see if the local or regional
		# probability of catastrophe occurrence is 
		# set to 0 for both catastrophes.
		# Check the html summary document, if available.
		# If all catastrophe probabilities are set to 0, 
		# ensure that all parameter(s) affected by 
		# catastrophes are unchecked. Save the changes 
		# to the RAMAS Metapop model.

# If a sink population is included in the Metapop Link 
	# file to simulate the effects of dispersal mortality: 
	# Open the *.mp file in RAMAS Metapop.
	# Delete the sink population.
	# Save the changes to the RAMAS Metapop model 
	# (GRIP automatically adds a sink population 
	# to evaluate the relative effects of 
	# dispersal survival).                              

# GRIP 2.0 has not been configured to vary the 
	# effects of population management scenarios. 
	# When GRIP 2.0 writes the RAMAS Metapop input 
	# files for the sensitivity analysis (Step 5), 
	# the default of no population management scenarios 
	# is assumed. The user could, however, customize 
	# the code to evaluate the effects of population 
	# management scenarios on population dynamics 
	# (e.g. Curtis J.M.R. and A.C.J. Vincent. 2008.
	# Conservation Biology 22(5):1225-1232).		
	
# And finally.....
# Format the RAMAS METAPOP Link model input file (*.mp) 
	# in a text editor:
	# 1. Open the RAMAS Metapop input (*.mp) file in a 
	#btext editor (e.g. TINN-R, Textpad, R Script editor). 
	# 2. Remove any appended results from the input files 
	# (i.e. all text lines below and including the line 
	# with "Simulation results" on it, if that line is present).
	# 3. If there are more than 24 columns in the 
	# population dataframe (i.e. dataframe immediately 
    # following line 44 of the input file), add a comma 
	# to the end of each row.
	# 4. Delete spaces, apostrophes ('), periods (.) or 
	# other unusual characters from population 
    # names (e.g. change "Pr. Edward" to PrEdward). 
#----END----------------------------------# 



#-----------------------------------------# 
# B. RAMAS GIS Spatial Data module 
	# input file preparation
#-----------------------------------------# 

# 1. Open the RAMAS GIS Spatial model (*.ptc file)

# 2. Ensure all parameters are specified, including 	
	# habitat-specific demographic and catastrophe parameters. 
    # Some relevant information for populating the 
	# RAMAS GIS Spatial Data file include:

    # Local probabilities of catastrophes and 
	# Local multipliers of catastrophes (under the 
	# Catastrophes tab) will always over ride those 
	# specified in the Metapop file. However, 
	# all settings and parameter values 
    # should be consistent between the Spatial (*.ptc) 
	# and Metapop (*.mp) files for GRIP 2.0 to write the 
    # final RAMAS Metapop input files correctly.
	
    # Temporal trends in local probabilities and local
	# multipliers cannot be specified in the Spatial Data 
    # program (*.ptc file). The current version of 
	# GRIP 2.0 is not configured to accommodate 
	# temporal trends but the code could be 
	# customized to do so by the user. 
   	
    # In this version, dispersal and Correlation distance 
	# function parameters must be specified in the 
	# Spatial Data program (*.ptc file). If they are 
	# left blank then no dispersal rates or correlations 
	# will be calculated and both the function and 
	# matrices in the final RAMAS Metapop input 
	# file will remain blank. This is because 
    # the Spatial module does not read the distance 
	# functions specified in the Metapop Link file. 
	# The user could specify user-defined dispersal 
	# and correlation distance functions within GRIP. 
	# Feel free to contact us for examples.

    # If initial abundance or carrying capacity (K) 
	# are constants (and not specified as a function of habitat 
	# suitability, area, etc), GRIP 2.0 will sample these 
	# from the distribution of abundances or carrying capacities 
    # specified in the Metapop Link file. So if only 
	# one population is specified in the metapop (*.mp) file and 
    # initial abundance or carrying capacity are constants, the final replicate model will have a 10% CV applied and 
    # habitat patches identified by the RAMAS algorithm 
	# will have the same initial population size and K.
 
 	# The "distribution of initial abundance to stages is 
	# taken from the first row in the Initial abundances 
    # dialog box of the metapopulation model file 
	# specified in "Other data from..." (Akçakaya 2005).
	
 
# 3. Habitat-based distances (e.g. from a friction map) 
	# should not be included in sensitivity analyses run with 
	# the current version of GRIP 2. A friction map can 
	# only be included if IDRISI32 is installed, 
	# but even if IDRISI32 is installed, this version 
	# of GRIP 2.0 does not vary friction map parameters.
 
# 4. Once the *.ptc has been configured as described above, 
	# and the *.ptc and *.mp files have been checked 
	# for consistency, run the "Find patches" command 
	# in the Spatial Data program.
 
# 5. Export the resulting habitat suitability map as 
	# an ASCII text delimited file. This is done 
	# through the 'File' drop down menu. Name the file 
	# using the following nomenclature: "Speciesname_HS.ASC", 
	# where Speciesname = the name of the modeled species 
	# (no spaces in the name).
 
# 6. Export and format the resulting patch map as an 
	# ASCII text delimited file. This is done through 
	# the 'File' drop down menu.
	# Name the file using the following nomenclature:
	# "Speciesname_PaID.ASC (no spaces in the name)
	# Open the ascii file in a text editor
	# Ensure that the Nodata value and the non-habitat 
	# value are the same, and are set to 0, by performing 
	# a 'find and replace' function. This is 
	# necessary for portions of the GRIP 2.0 program 
	# to function properly
 
# 7. In the Spatial Data program, replace the original 
	# habitat suitability function (see Habitat 
	# relationships, under the Model drop down menu 
	# of the Spatial Data program) so that the 
	# new function = [newly created habitat suitability map], 
	# (i.e. "[Speciesname_HS]"). Ensure that square 
	# brackets are used [] when specifying the new 
	# habitat suitability function.
    	
# 8. Replace the original input maps with the newly 
	# created .ASC file of habitat suitability. To do this, 
	# go to Input Maps under the Model drop down menu 
	# of the Spatial Data program. 
 
# 9. Remove any original input maps unless they are 
	# used to specify a habitat-demographic function. 
	# They are accessed through the Input Maps under 
	# the Model drop down menu of the Spatial Data 
	# program. Ensure that the newly created .ASC 
	# file of habitat suitability is the FIRST 
	# input map indicated. 
 	
# 10. Save the updated *.ptc file as "pre_Speciesname.ptc"  
	# and ensure that you SAVE RESULTS.
#----END----------------------------------# 
 
 


#-----------------------------------------# 
# Prior to Running GRIP 2.0: 
# General Specifications
#-----------------------------------------# 

# 1. Ensure all required files are in the working directory: 
			
	# A. Ensure that GRIP_2.r is in the R working directory.
			
	# B. Create a file named batch_GRIP2.txt by pasting 
	# the text below into a *.txt file (omit the # symbol 
	# from each line) 
	# make sure to change line3 to reflect the location 
	# of your RAMASGIS Patch.exe file location
	# Ensure the batch_GRIP2.txt file is located in the 
	# working directory 

		#START /WAIT
		#"GRIP2"
		#"C:\Program Files\RAMAS GIS 6\SpatialData.exe"
		#"
		#" /RUN=YES /TEX
     			 
       	
	# C. Create a file named batch.txt by pasting the 
	# text below into a *.txt file (omit the # symbol 
	# from each line):
	# Line 3 should be your path location for RAMAS Metapop
	# Ensure the batch.txt file is located in the 
	# working directory 
      
		#START /WAIT
		#GRIP2
		#C:\Program Files\RAMAS GIS 6\Metapop.exe
		#/RUN=YES /DAT=
		#/TEX
			
      			
	# D. RAMAS Metapop Link file (*.mp)
	# E. RAMAS Spatial Data file (*.ptc), remember that 
	# results must be saved and included in the 
	# working directory also.
	# F. Formatted habitat suitability ascii file 
	# (Speciesname_HS.ASC)
	# G. Patch ID ascii file (Speciesname_PaID.ASC)
	# H. Include any files required to run simulations 
	# using the original *.mp model in the working 
	# directory (e.g. temporal trend files)

   
# 2. To change the number of replicate simulations:
	# Change the number of "Nreps" in the User-specification 
	# section (the user-specified section starts around line 315)
	# Note that the time required for sensitivity analysis 
	# will depend strongly on the number of Nreps specified.
	# Try setting Nreps to a small number for trial runs 
	# with a new model or customized GRIP 2.0 code 
	# (e.g. Nreps=2).
		
# 3. To change the number of stochastic runs within 
	# each simulation (default is 1000):
	# Change the number of "Nruns" in the User-
	# specification section

# 4. Specify code in the user-specification section 
	# (the user-specified section starts around line 315),
	# including:
    # The name of the RAMAS Spatial Data file (of 
	# format "speciesname.ptc")
    # The name of the RAMAS Spatial Data habitat 
	# suitability file (of format "speciesname_HS.ASC")
    # The name of the RAMAS Spatial Data patch ID file 
	# (of format "speciesname_PaID.ASC")

# 4. Install the required software packages:
	# Ensure RAMAS Metapop 5.0 is installed on the computer.
	# Ensure R is installed (for free download 
	# and instructions, see www.r-project.org).

# 5. Source Grip2.r in R 
#----END----------------------------------# 


#-----------------------------------------# 
# Literature Cited
#-----------------------------------------# 

# Akçakaya, H.R. 2005. RAMAS® GIS Help File. Applied Biomathematics. New York.

# Curtis, J.M.R. and I. Naujokaitis-Lewis. 2008. Sensitivity of population viability to spatial and nonspatial parameters using GRIP. Ecological Applications 18:1002-1013.

# Curtis J.M.R. and I. Naujokaitis-Lewis. 2008. Source code for GRIP 1.0. Ecological Archives A013-033-S1.

# Curtis J.M.R. and A.C.J. Vincent. 2008. Use of population viability analysis to evaluate CITES trade-management options for threatened marine fishes. Conservation Biology 22(5):1225-1232.


#-----------------------------------------# 
# Additional notes: sampling protocols
#-----------------------------------------# 

# The way that GRIP 2.0 varies some parameters can be changed easily by users who wish to consider 
# alternative sampling distributions. 
# Here, we briefly describe some of the key parameters that are varied and provide some suggestions on 
# how users can vary sampling distributions.

# further details are provided throughout the code. 

# Distance measure among patches
    # By default, RAMAS Spatial calculates distances between patches by center to center distances.
    # The code is currently configured to vary how distances are calculated

# Change in patch size
    # The default setting used to sample the % that each patch will change is based on a uniform distribution 
    # with a minimum = -0.50 (equivalent to a 50% decrease in size) and a maximum = 0.50 (equivalent to a 50% increase in size)
      #patch_change<-round(runif(1, min = -0.50, max = 0.5),3)
    # The user can adjust the sampling protocol applied for their specific circumstances
    # See code at approximately line 1155 to adjust min and max values

# Number of populations
    # Currently, the number of populations in each replicate simulation is sampled from a 
    # normal distribution assuming a 50% CV with the original number of populations as the mean
    # The range in the number of populations can be varied by revising the corresponding code (around line 830)

# Size of patches added to the landscape
  # Current protocol is a function of the average and standard deviation of the area (# of cells) of 
  # patches within the original landscape
  # The new radius is sampled from normal distribution with mean = the square root of the mean area of 
  # current patches divided by 2, and standard deviation = to a similar function
  # In calculating the new radius, we assume, for simplicity, that the original patch shape was square

# New patch centres are sampled a minimum distance of 5 times the original cell size to ensure that 
# new patch centres are not located too close to one another.


#-----------------------------------------# 
# Additional Notes: Miscellaneous
#-----------------------------------------#

#	For meaningful interpretation of spatial sensitivity analysis, dispersal-distance and correlation-distance 
# function parameters should be specified (even if they simply represent constants)

#	Inclusion of temporal trends in the PVA model will likely require additional customization of the code, feel 
# free to contact us for examples. 

#	If both sexes are modeled separately, or if multiple transitions are included in the stage and standard deviation 
# matrices, the vital rates will not be recorded properly in the data.csv table, and the user will need to write user-defined
# code to extract all transition probabilities from stage matrices in the rep_*.mp files. 

#	Occasionally, an assertion failure error occurs (e.g. W:\GROUP\RG4\METAPOPW\Main.pas, line 620), which we 
# generally attribute to random parameter values drawn from the specified distributions that exceed constraints 
# within RAMAS software. When an assertion failure error occurs, results are not recorded for the current replicate 
# simulations. Consequently, GRIP 2.0 will not be able to collate data from the results files as programmed. 
# We have a few (more laborious) solutions to this problem, but you could try re-sourcing the GRIP 2.0 code and 
# hope that assertion errors do not crop up again... 

# GRIP 2.0 uses objects and functions specific to many spatial extensions in R. R spatial objects can be quite large, 
# which may pose a problem with the functioning of GRIP 2.0 because there are limits on the memory that R can use. 
# The function 'gc()', or garbage collection, is peppered throughout the code to help decrease memory usage. Please see 
# R for Windows FAQ, section 2.9 (http://cran.r-project.org/bin/windows/rw-FAQ.html) for more information.

#	For temporal trends or issues with vital rates and assertion failure errors, please contact us. 
# We have an additional set of custom tools and code for collating data and incorporating temporal trends in sensitivity analyses.