RAMAS Workflow Instructions

RAMAS is immensely powerful, but seems to require some finesse in setting up the models, and is somewhat unclear as to what parameters need to be set…and when and how. In this tutorial, we walk readers through an example to provide a basis of understanding on how to set up and run analyses in this program. This will also serve as a record for purposes of reproducibility.

Note for readers: This is not an exhaustive tutorial, and there are many settings we skip over because they are not applicable to our study.

Overall workflow:

  1. Set RAMAS configurations to increase the size of allowed input raster.
  2. Prepare spatial information and create habitat layer, determine suitability thresholds.
  3. Build template Metapop file (template.mp) with demographic information.
  4. Import habitat layer into Spatial Data and link Spatial Data file to template.mp
  5. Identify habitat patches
  6. Export new Metapop file that includes populations based on habitat patches
  7. Make final edits to pop model, run simulation
  8. Perform sensitivity analysis and compare results
  9. Plotting patches and converting ASCII patch file to .tif (R & ArcGIS Pro)

1. Edit RAMAS Config Module

  1. To be able to import the entirety of a large raster, you have to change the number of raster cells in the configuration module. In the Maxima tab, the default number of rows and columns (400 rows, 500 columns) is too few, in our case for Mississippi at a 1 km2 resolution. Therefore, we changed the map rows and map columns values (in red box in figure below) to slightly higher than the dimensions of our raster (545 rows, 317 columns). RAMAS has a limit of 16,000 cells in both columns and rows. Click save.

    Maxima tab of CONFIG subprogram

  2. Now we need we save the correct file path so that the changes we made apply when we build the models. Go to the ‘Other’ tab. At the right of the box that says Data File Path, click on the button with three dots and navigate to the folder where you will be saving your RAMAS Models. Click Save and exit the Configuration module. *Note: Check the manual if this is not working.

    ‘Other’ tab of CONFIG subprogram

2. Prepping Raster Files

RAMAS provides the option of imported a pre-made habitat suitability layer (hereafter referred to as ‘habitat layer’), or importing individual spatial layers and calculating suitability manually. Here, we built the habitat layer in R and predicted across the study area, and will therefore only need the final predicted layer to import. We will use the terra package in program R to format the habitat layer and export it as an ASCII (pronounced ‘ask · ee’; .asc file extension) file so that it can be read in by RAMAS, though you can also prepare spatial information like this in ArcGIS Pro (ESRI) or other GIS programs. An example of how a habitat suitability layer could be produced using R is provided below:

library(tidyverse)
library(terra)
library(lme4)

# Load polygon of study area
ms_full <- vect("data/landscape_data/mississippi.shp") 

# Load point locations
dat <- read_csv("data/location_data/gps_locations.csv")

# Load habitat rasters (90x90 m resolution)
layers <- c("data/habitat1.tif", "data/habitat2.tif")
layers <- rast(layers)

# Run resource selection function. This model assumes we have a data frame called 'dat' that has a column of 0s (available) and 1s (used) in the 'used' column. Each row has extracted landscape data, in columns 'habitat1' and 'habitat2', which were extracted from rasters now stored in 'layers'
rsf <- glmer(used ~ habitat1 + habitat2 + (1|ID), data=dat, 
             family=binomial(link = "logit"))

#### Now we will predict habitat selection across the raster layers
# If you want 95% confidence intervals, skip this part and go to the section below
pred <- predict(layers, rsf, type="response", re.form = NA)

# Make template raster (what you want the final resolution to be - here, we use 1000 m)
temp_rast <- rast(ext(ms_full), resolution=1000) 

# Resample to resolution of template raster
pred <- resample(pred, temp_rast)

# Mask and crop the predicted output so that there are as few extra lines of no data or data outside the study area as possible using vector information
pred <- mask(pred, ms_full)
pred <- crop(pred, ext(ms_full))

# Rescale raster to be between 0 and 1
pred <- (pred-minmax(pred)[1])/(minmax(pred)[2]-minmax(pred)[1])

# Fill missing data with 0
m <- rbind(c(NA, 0))
pred <- classify(pred, m)

# Write .tif
writeRaster(pred, "data/predictions/rsf_FINAL.tif")

# Write ASCII file
writeRaster(pred, "data/predictions/rsf_FINAL.asc", NAflag=-9999)
# Note: include the argument overwrite=TRUE in writeRaster() to rewrite over the old file if you need to rerun something.

#### Predicting habitat suitability with uncertainty 
# (mean + 95% confidence intervals for predictions)

# We need to change our approach here to obtain uncertainty values. When we are predicting from a binomial GLM/GLMM and include type="response" in predict(), predict() converts the reponse to predicted probabilities. However, if we include se.fit=TRUE, this conversion is not done for the standard error values, which are instead returned on the log-odds scale. We deal with this by predicting both the mean predicted value and SE on the log-odds scale, calculate the 95% CI, and then transforming all three values (mean lower CI, upper CI) tothe probability scale.  

# Another issue that we run into is that with large rasters, calculating SE will crash R. A workaround is to generate point locations at the center of each raster cell (in ArcGIS Pro, for example), and then assign the raster values to each point. 

# Read point locations (raster cell centerpoints)
pts <- vect("data/landscape_data/ms_masked_90m_pts.shp")
pts <- project(pts, crs(layers))

# Extract raster values at points (i.e., put the raster values into a data frame)
pts_extr <- extract(pig_layers, pts)
pts_extr <- pts_extr %>% select(-ID)

# Predict values. Set type="link" so that everything is on the same (log-odds) scale 
pigs_se <- predict(rsf, newdata=pts_extr, type="link", se.fit=TRUE, re.form=NA)

# Create tibble for calculations
pigs_se <- data.frame(fit=pigs_se$fit, se.fit=pigs_se$se.fit)

# Calculate confidence intervals
pigs_se <- pigs_se %>% as_tibble() %>%
  mutate(lci=boot::inv.logit(fit - (1.96 * se.fit)),
         uci=boot::inv.logit(fit + (1.96 * se.fit))) %>%
  mutate(fit=boot::inv.logit(fit)) 

# Add calculated/transformed values to the points vector object to associate predictions/uncertainty with spatial locations
pts$fit <- pigs_se$fit
pts$lci <- pigs_se$lci
pts$uci <- pigs_se$uci

## There are a couple of ways to convert the points back to a raster. Do one or the other, but not both

# Option 1. Open the point file in ArcGIS and convert it to a raster
# Write shapefile
writeVector(pts, "data/landscape_data/pigs_pts_se.shp", overwrite=TRUE)

# After writing the shapefile, open it in ArcGIS and used the Point to Raster tool (in Conversion Tools) to convert the point file to a raster for each column of the pts file. 

# Then, read the converted rasters back into R
pigs_uci <- rast("data/predictions/pigs_glmm_rsf_UpperCI.tif")
pigs_lci <- rast("data/predictions/pigs_glmm_rsf_LowerCI.tif")
pigs_mean <- rast("data/predictions/pigs_glmm_rsf_mean.tif")

# Option 2. Convert points to raster. This is nice for the workflow, but depending on the size of your raster, is very memory-intensive
# The second argument is a raster that matches the resolution of the pts SpatVector (i.e., 90x90)
pigs_uci <- rasterize(pts, layers["habitat1"], field="uci", fun="mean")
pigs_lci <- rasterize(pts, layers["habitat1"], field="lci", fun="mean")
pigs_mean <- rasterize(pts, layers["habitat1"], field="fit", fun="mean")

## Once we have prediction and CI rasters, we can continue with resampling, transforming, and cropping 

# We need to crop the the raster so the extent is only as big as the study area, otherwise RAMAS will count all those cells of NAs towards your row/column limits
pigs_uci <- mask(pigs_uci, ms_full)
pigs_lci <- mask(pigs_lci, ms_full)
pigs_mean <- mask(pigs_mean, ms_full)

## Rescale so that suitability is on a scale of 0-1, but need everything to be on the same 0-1 scale
# find min and max values
max_hsi <- max(minmax(pigs_uci)[2], minmax(pigs_lci)[2], minmax(pigs_mean)[2])
min_hsi <- min(minmax(pigs_uci)[1], minmax(pigs_lci)[1], minmax(pigs_mean)[1])

# apply scaling to all three rasters
pigs_uci <- (pigs_uci-min_hsi)/(max_hsi-min_hsi)
pigs_lci <- (pigs_lci-min_hsi)/(max_hsi-min_hsi)
pigs_mean <- (pigs_mean-min_hsi)/(max_hsi-min_hsi)

# Mask lakes
pigs_uci <- mask(pigs_uci, lakes, inverse=TRUE)
pigs_lci <- mask(pigs_lci, lakes, inverse=TRUE)
pigs_mean <- mask(pigs_mean, lakes, inverse=TRUE)

# Resample to 1x1 km
pigs_uci <- resample(pigs_uci, temp_rast)
pigs_lci <- resample(pigs_lci, temp_rast)
pigs_mean <- resample(pigs_mean, temp_rast)

# Reclassify missing data to 0
m <- rbind(c(NA, 0))
pigs_uci <- classify(pigs_uci, m)
pigs_lci <- classify(pigs_lci, m)
pigs_mean <- classify(pigs_mean, m)

## Save mean, LCI, and UCI rasters as .asc files for import into RAMAS
writeRaster(pigs_uci, "data/predictions/pigs_glmm_rsf_UpperCI.asc",NAflag=-9999, overwrite=TRUE)
writeRaster(pigs_lci, "data/predictions/pigs_glmm_rsf_LowerCI.asc",NAflag=-9999, overwrite=TRUE)
writeRaster(pigs_mean, "data/predictions/pigs_glmm_rsf.asc",NAflag=-9999, overwrite=TRUE)
# Additionally save mean predictions as .tif for plotting if desired. This raster should be more or less the same as the pred raster, but note that values might be a little different due to scaling
writeRaster(pigs_mean, "data/predictions/pigs_glmm_rsf.tif", overwrite=TRUE)

3. Determine suitability thresholds

Now that we’ve created a habitat layer, we need to determine the threshold that we will consider “core” habitat. We recommend doing this in the same R session as creation of the habitat layer. Hold on to this value, we will need in RAMAS Spatial Data. An example of how this could be extracted is:

# Set up data frame with limited columns (don't need the habitat values we extracted earlier)
pig_test <- dat %>% select(PigID,used,X,Y)

# Extract RSF predictions at each location 
dat_pig <- extract(pigs_mean, pig_test[,c(3:4)]) 

# Add extracted values to data frame
pig_test$rsf <- dat_pig$mean

# Create a vector from 0 to 1, increasing by 0.01
thresh <- seq(0,1,by=0.01)

# Create an empty matrix, then add the threshold values to the first column
res <- matrix(NA, ncol=3, nrow=length(thresh))
res[,1] <- thresh

# Loop over each threshold value
for (i in 1:length(thresh)) {
  
  # Convert the 'used' column to a factor with levels 0 and 1
  actu <- factor(pig_test$used, levels=c(0,1))
  
  # Determine whether the habitat suitability value is greater than the threshold, and set to 0 or 1
  pred <- factor(if_else(pig_test$rsf >= thresh[i], 1, 0), levels=c(0,1))
  
  # Use the caret package to compare 0 and 1 values that were predicted vs actual
  # Save sensitivity and specificity values into the matrix
  res[i,2] <- caret::sensitivity(pred, actu)
  res[i,3] <- caret::specificity(pred, actu)
}

# Convert matrix to data frame and rename columns
res <- res %>% as.data.frame() 
names(res) <- c("Threshold", "Sensitivity", "Specificity")
# Calculate true skill statistic
res <- res %>% mutate(TSS = Sensitivity + Specificity - 1)

# Print the row that maximizes true skill statistic
res %>% slice_max(TSS)

4. Set template demographic parameters in RAMAS Metapopulation

  1. We need to create a “template” population file that will be used by the Spatial Data module. RAMAS Spatial Data will take the demographic information from this template and use it to populate individual patches with starting demographic information when we export a metapopulation file from Spatial Data, and incorporate the spatial configuration when we run the metapopulation model. It is recommended to fill out Stages, Sex structure, Stage matrix, Standard deviation matrix, Stochasticity, and Catastrophes sections for import into Spatial Data. Open then RAMAS Metapopulation subprogram.
  2. In the top of the program window, click on Model. This will open a list of the sections that we need to edit. We will fill these out starting at the top of the list and moving down.
  3. Start with General Information.
    • Add a title (e.g., ‘Pigs template’) and optionally any comments.
    • Leave Map features blank.
    • Change the number of replications - this is the number of times the population will be simulated, and if incorporating stochasticity there should be multiple replications, but if no stochasticity will be incorporated into the final model, leaves as 1. We set this to 5000.
    • Set the Duration (number of time steps) you wish the simulation to be projected. In our case, we projected the population over 10 years.
    • Enter a value to specify the interval of a time step. You can select from the drop-down to change time steps to have values of months, days, or years (default). In our case, we want a timestep equal to 1 year, so we enter 1 in the box. Hit ok to close the menu.
  4. Next, open the Stages menu. This is where we tell RAMAS about the population structure

    • Name: List the ages or stages that will be included in your population model. It is helpful to indicate sex along with the stage/age name to keep everything organized. For example, we have three stages for both males and females. Always start listing female stages first, then males stages. In our pig model, we had three stages for each sex: piglets, yearlings, and adults, so in total we had 6 stages listed in the Stages menu. Click Add to add a stage.

      Stages menu for wild pigs in MS. Three stages each for males and females

    • Relative Dispersal: When there are multiple patches, RAMAS will calculate a dispersal rate between patches (based on function in Dispersal menu, which we won’t edit in the template population). The Relative Dispersal column is relative to the overall dispersal specified in the Dispersal dialog. At least one stage should have relative dispersal of 1. A value of 0 means that individuals in that stage do not disperse. Note that this is NOT the same as natal dispersal within a patch, though those values may be used to set relative values (e.g., between males and female dispersers). For example, because 54% of male pigs disperse while only 35% of female pigs disperse, we set male piglet relative dispersal to 1, and female pig dispersal to 0.35/0.54 = 0.65. We included a small percentage for dispersing yearling males. Note that this value only comes into play when there are >1 patches identified by RAMAS Spatial Data.

    • Average Weight: Used when calculating harvest ratios. Leave as 1 unless explicitly modeling harvest.

    • Exclude: Switching to ‘Yes’ will exclude that particular stage from the population total. Otherwise, all stages are summed when calculating abundance.

    • Basis for DD: Carrying capacity will be calculated based on stages marked as ‘Yes’, and thus could be used to model competition for territories.

    • Breeding: The breeding column is to indicate the proportion of each class that is physically/physiologically capable of breeding, not the proportion of individuals that typically breed in a given year (which should be incorporated into fecundity values). This value ranges 0-1, and any stage with a fecundity should have a value >0 in the Breeding column. Because pigs can reach sexual maturity by 5 or 6 months, we entered a value of 0.5 for piglets.

    • Click OK to close the Stages menu.

  5. Open the Sex Structure menu

    • The Sex Structure menu tells RAMAS how you are modeling populations. The default is a females-only model.

    • Determine from the list which best represents your population. In our study, we selected Both males and females, in separate stages.

    • Because we selected the option with both males and females, we need to specify the number of female stages. As noted in the program, we usually have the same number of male and female stages (but often vital rates may vary between sexes). Here, we had 3 stages for females (pigs, yearlings, and adults) because we had 6 total stages.

    • We also need to specify the mating system because we have both males and females in our model. We selected polygynous for pigs, and we assume that males can have unlimited partners (i.e., they can mate with any receptive female they come across). Click OK to save and close the Sex Structure menu.

      Sex structure menu with options selected for wild pigs
  6. Open the Stage Matrix menu

    • The stage matrix is where you enter the survival and fecundity values for each age or stage. Multiple matrices can be added, for example, if different population dynamics are expected in different areas/under different conditions.

    • In general, fecundities are placed in the top row. In a female-only matrix, these values represent the number of female offspring produced per female. In a 2-sex matrix, we additionally include the male offspring produced per female of each age/stage, but on a separate line. Survival rates from one age/stage to the next follow the sub-diagonal, while the diagonal represents the probability of surviving in a stage but not moving on to the next (not relevant for age matrices). Thus, in the matrix below, there are three stages that only last 1 year, while individuals in the 4th stage can stay in that stage for multiple years.

      Visualization of demographic data in a 2-sex matrix model with 4 stages

    • In a 2-sex matrix, the top right quadrant will be gray because these should all be 0s (with the exception of species that change sex by stage). Additional matrices can be added by clicking the Add button. Each matrix can be given a unique name. The Fecundity and Survival coeff parameters can be left as 1, these are used only when creating a new matrix, in which you want to change the vital rates by a constant coefficient. In that case, you would add a value in the coeff box, then click Auto Fill.

      Stage matrix menu for a model including both males and females

    • We need to add constraints for RAMAS to account for vital rates properly. Click on Constraints and then Auto Fill and click OK to save and exit.

    • Click OK to save and exit the Stage Matrix menu

  7. Open the Standard Deviation Matrix menu

    • The standard deviation matrix provides values for each parameter to incorporate demographic stochasticity. This matrix should have stand deviations in the same matrix cells where survival and fecundity were added in the stage matrix, unless it is desired to model stochasticity in only some parameters.

    • Instead of manually filling the standard deviations, RAMAS can auto-fill the Standard deviation matrix using coefficient of variation. Click on Auto Fill in the bottom left corner. We can allow for 10% variability in vital rates by filling in 0.1 in both text boxes.

      Auto Fill dialog box of Standard Deviation Matrix menu

    • Click OK to close Auto Fill, then OK again to save and close the Standard Deviation Matrix menu.

  8. Stochasticity menu: We did not add this to our model because stochasticity was already incorporated as uncertainty in vital rates and we have a relatively stable population of pigs across the state. In other words, we are not trying to model extinction or explosion, so we were OK with accepting the defaults here. However, if you want to incorporate these sorts of dynamics this would be the place to do so.
  9. Catastrophes menu: The catastrophes menu is for incorporating rare, devastating effects (e.g., hurricane or wildfire). There is the option to specify two catastrophes and control how they affect the population. For our study, our species is not subject to major catastrophic events, so we did not incorporate catastrophes.
  10. Save the metapopulation file (e.g., pigs_template.mp) by clicking on File > Save. Note that the main screen has been populated with the values you entered (including replications, number of stages, density dependence, etc.). Close the Metapopulation subprogram.

5. Importing spatial data and linking to demographic information

  1. Open the RAMAS Spatial Data subprogram.

  2. Again, at top of the program window, click on Model. This will open a list of the sections that we need to edit, similar to RAMAS Metapopulation.

  3. Fill in General information.

    • As in the Metapopulation subprogam, we want to give the session a title (does not need to be the same as what you will save the file)
    • Add comments if necessary or helpful.
    • Change the value in the cell length box to reflect the resolution of your rasters. Since we are using a 1 km2 raster, we can leave the value as 1, but if we would have had a larger raster cell size (e.g., 2.25 km2), we would need to adjust this value to 1.5.
    • Leave map features blank again.

  4. Go to Model > Input maps to load habitat layers

    • Click Add, which will population the ‘Maps:’ section with ‘Map 1’.
    • You can change the name of Map 1 to something more informative, such as PigMeanHSI
    • In the line that says File:, click on the button with three dots and navigate to the folder with your habitat layer. You may need change the filetype (in the bottom right )to All files (*.*) in order to see available .asc files. Select the habitat layer you want to import and click OK.
    • Format will automatically population (it should read ARC/INFO if you’ve read in an ASCII file).
    • Click on the View button (bottom left corner of Input Maps menu). This will show you a preview of your habitat layer, and it will give you a warning if the entire raster is unable to load. In that case, you will need to go back and readjust the RAMAS configuration to increase the number of rows or columns.
    • After closing the View window, # of columns will automatically populate.
    • Once the desired rasters are loaded, click OK and close the window.

  5. Next, go to Model > Habitat relationships

    • This section controls how RAMAS delineates the patches. It is possible to upload habitat layers and specify a suitability function within RAMAS; however, the modeling capabilities are limited. Thus, we imported the raster generated from resource selection modeling, but still need to specify a function for habitat suitability. In this case, it is just the imported layer * 1. Note that the name of the habitat layer must be in square brackets. Do not include and equal sign (=).

      Settings for mapping pig core patches

    • The habitat suitability threshold for patches is the suitability value that RAMAS will use to convert the continuous habitat layer into a binary patch map, while everything below the threshold becomes “matrix”, or unsuitable habitat. This should be determined as part of the habitat suitability modeling process in R, or using other criteria.

    • The Neighborhood distance specifies the distance between discrete sections of suitable habitat that can considered a single patch. The RAMAS manual illustrates (p. 15) the distances for values 1.2 to approximately 2.8, and recommends using these values. However, large values may be included, but it will likely impact computation time. Here, we used a distance that was approximately twice the average dispersal distance (e.g., average for pigs is 4-5 km, so we used a value of 10 km).

    • Habitat suitability map color and Decimals for habitat suitability can be left as default; they control the visualization of the habitat map that is generated if one is calculated in the function box.

    • Click OK to save and close the habitat relationships menu.

  6. Go to Model > Link to metapopulation. This menu is where we connect the template metapopulation to the habitat patches.

    • There are two tabs: General and Catastrophes. Most of the information will be contained in the General tab.

    • The first option allows us to specify a function that will determine carrying capacity for each patch and the overall study map. RAMAS has four patch variables built in (p. 16 in the RAMAS user guide): total patch suitability (ths), average patch suitability (ahs), number of cells in the patch (noc), and the length of the patch perimeter (per). Thus, these can be used to adjust the population parameters according to patch attributes. The RAMAS manual (p. 28) describes functions that can be used to incorporate these variables (beyond simple mathematics). In our model, we wanted to set the greatest suitability to reflect a density of 8 wild pigs/km2, and reduce the density as suitability decreased. Thus, we multiply 8 wild pigs/km2 by ths. Note: our habitat layer is a 1 km2 grid, so we can use 8 wild pigs in the calculation. However, if we had a coarser grid, say 1.5 x 1.5 km (2.25 km2), we would need to account for this in density (e.g., 18 pigs per 2.25 km2 grid cell).

      Link to Metapopulation menu for wild pigs in Mississippi

    • The maximum growth rate (Rmax) is a tricky parameter. It represented the maximum finite rate of increase (often represented as 𝜆) for a population, when the population is not experiencing effects of density dependence. This value must be >1 even if the population being modeled is expected to decrease. We looked for population modeling studies in the literature that estimated 𝜆 and used the highest as a starting point, but note that this has implications for the strength of density dependence when incorporated into a metapopulation model. The RAMAS user guide provides some context.

    • Next, we need to specify an initial abundance for each patch. Giving just an integer will assign this value to every patch, regardless of size or carrying capacity. RAMAS allows for functions to determine initial abundance, similar to carrying capacity, to adjust for overall patch suitability, size, etc. The default given in the manual is noc * 1.2 - per * 0.1, which incorporates the number of cells and the length of the patch perimeter in determining the initial abundance. We edited this function to be (noc * 8 * ahs) - per * 0.1, where 8 is the density of wild pigs/km2.

    • Similarly, we can adjust vital rates according to suitability values in each patch by specifying functions in the Relative fecundity and Relative survival options. For this model, we maintained all survival and fecundities equal to 1 (i.e., all the same).

    • We do the actual linking to the template metapopulation file in the Other data from option. Click on the button with three dots. Navigate to and select the metapopulation file you created in section 3: 4. Set template demographic parameters in RAMAS Metapopulation

    • The final parameter that can be edited in this menu is for Distances. This will tell RAMAS how to calculate the distances between patches, with the options being edge to edge, center to center, or center to edge. We selected Edge to edge.

    • Before closing the menu, one can specify local multipliers and probabilities for catastrophes under the Catastrophes tab. We did not have any catastrophes that needed to be adjusted spatially, so we left these blank.

    • Click OK to save and close the window.

  7. Go to Model > Default population

    • There are three tabs in the Default population menu: General, Density Dependence, and Catastrophes. Again, we left the Catastrophes tab blank, as we were not incorporating these into our model.
    • The General tab shows several parameters, but most are calculated by RAMAS or specified in the Link to Metapopulation tab. Only the Local threshold parameter is available for editing, which can be used to specify patches that are included in the summation of abundance when running the metapopulation model. We set this to 5, assuming that most populations would need more individuals to persist.
    • The Density Dependence tab will allow us to assign parameters for density dependence. We set the Density dependence type to Scramble so that this would be applied to all populations generated with patches. We also incorporated some environmental stochasticity by setting Standard deviation of K to 1000, but can be changed to include more or less stochasticity. We left the remaining parameters as default (usually 0).
    • Click OK to save and exit this menu.

  8. Go to Model > Dispersal

    • The Dispersal menu will allow us to specify a function that controls how far animals disperse between habitat patches, which will calculate dispersal rates for the metapopulation. There are four parameters: a, b, c, and Dmax. It is unclear what these all represent, but the manual (p. 31) recommends setting a and c to 1 so that the dispersal function simplifies to a negative exponential. We then specified b as 5.0 to represent 5 km, the average natal dispersal for wild pigs, and Dmax as 65 km, which we determined from the literature was on the upper limit of wild pig dispersal distances.
    • The View Function button will only show results after RAMAS has found \(\geq\) 2 patches.
    • Click OK to save and close the menu.

  9. The Model > Correlation menu allows one to specify how different patches/populations are correlated with each other. We left these as default values.

6. Calculate Patches

  1. After filling in the menus under Model, we can now tell RAMAS to calculate the patches.
  2. Go to Find patches > Run.
    • This will open a new window showing the progress of the calculations. It will also copy the information from General Information to show what is being run. For our wild pig models, this takes <1 second, but may take longer depending on the neighborhood distance and resolution of the habitat layer.
    • When the program has finished, it will show ‘End of calculations’ in the message window and ‘Completed’ at the bottom of the window, along with the time it took.
    • Click OK to close this window.
  3. After calculating patches, we can explore the Results tab of the main RAMAS Spatial Data program. It would be beneficial to click on the Save button before proceeding further, and selecting Yes when the dialog asks if you would like to save the results.

    • Before delineating patches, all of the options under Results will be grayed out, and will become available after calculating patches. Not every option will be relevant for every analysis, so we discuss only the ones examined in this study.

      Results menu of RAMAS Spatial Data

    • The Habitat suitability map will open a map of patches labeled by population. The way this map is visualized can be edited by going to View > Options, and changing the option for Draw patches as. The ‘solid’ option may be preferred, as it shows only the patches, with each presented in a different color. This visualization can be exported (see section 7).

    • Next, we open the Carrying capacity results. It will open a graph showing carrying capacity (K) on the y-axis, and population (the patches) on the x-axis. We can also look at this in tabular format by clicking on the Text tab, just above the graph. The text results can be saved as a .txt file for later reference. In addition to patch-level habitat suitability values and carrying capacity, this table also shows the initial abundance for each patch.

    • Similarly, we were interested in examining the Area of the patches found by RAMAS. It again opens to the graph of Area vs patch, with the option to switch to the Text tab. The Area results provide the size of each patch, as well as the area of core patch (i.e., not edge cells), as well as several landscape configuration metrics, with sums and averages found at the bottom of the table.

    • We can preview the populations that were assigned to each patch by opening Populations. This is what will be exported to a Metapopulation file in the next step.

7. Export Results and Metapop file from Spatial Data module

  1. It is helpful to export two things after calculating the patches: patch map (helpful for visualizations/manuscript figures) and a Metapopulation file (necessary for continuing the process). Both of these can be accomplished by going to:
    • File > Save RAMAS Metapop file… Navigate to the desired folder and provide a file name, then click Save.
    • File > Export patch map… Navigate to the desired folder and provide a file name, then click Save. Note that this will write an ASCII (.asc) file, that can be read into ArcGIS Pro and R and converted to a .tif or other file format.

Exporting patch map and Metapop file from Spatial Data

8. Running the actual Metapopulation model

  1. Open the Metapop file that was exported from RAMAS Spatial Data. This can be done by double-clicking the exported .mp file instead of opening RAMAS Metapopulation from the Start menu. Since we set up an initial template population in step 4, we won’t need to edit as much here.

    Wild pig template metapop (left) and metapop exported from spatial data (right)
    • If the type of density dependence was not specified in the template, go to Model > Density dependence. In the drop down menu for Density dependence affects, we parameterized the model so that density only affected fecundities. We also checked the radio button for Density dependence (and carrying capacity) is based on the abundance of All stages. Finally, we checked the button for All populations have the same density dependence and selected Scramble from the drop-down menu.
    • Population-specific information can be viewed by going to Model > Populations and clicking the Display button in the lower left corner of the General tab. This opens a new menu to show population-specific data, such as how the population is impacted by density dependence, catastrophes, etc. The first option Finite Rate of Increase (lambda) will open a window displaying the population matrix, elasticities, and sensitivies, but doesn’t account for stochasticity, density dependence or sex structure/mating system (full list shown in the window). It also provides an approximate growth rate for the population. Many of the additional options will be more relevant if modeling differences in vital rates between patches.

  2. Go to Simulation > Run. This will project the population out to the specified time frame.

    • RAMAS will open a new window as the simulation runs, with the very bottom of the window showing the replication and time step as it calculates. There is a progress bar at the top that will fill green as the simulation runs.

      Running simulation - default window

    • It is also possible to view the simulated population trajectories (i.e., abundance for each replication and time step) as the run by clicking on the graph icon at the top of the simulation window (third from left).

      Simulated population trajectories

    • When incorporating density dependence, there will sometimes be a warning message that the stage matrix is possibly inconsistent. This is not an error, and may occur when density dependence adjust the growth rate so that it is different from what would be due to the population matrix alone. Click the red question mark button for the Help file for more information.

    • After the simulation has completed, close the window by clicking the X in the upper right-hand corner. There is no option to save here, the simulation results can be saved from the main Metapopulation program window. If incorporating this simulation in a sensitivity analysis below, the Sensitivity Analysis program will re-run the simulations.

  3. Results can be viewed under the Results tab, similar to how we viewed the results from RAMAS Spatial Data.

    • Results > Trajectory Summary will show the calculated population trajectory across time steps and summarized over all replications. Again similar to the results in Spatial Data, we can view the results graphically or as text.
    • There are many Results options that were not relevant to our analysis.
    • Notably, there doesn’t seem to be a tab that calculates population growth rate (𝜆) while incorporating density dependence and stochasticity, etc. However, we can calculate it in R using the values from Trajectory Summary

      1. Go to Results > Trajectory Summary, then select the Text tab. Click Save. This will write a .txt file in the specified location.

      2. The following code can be used to calculate 𝜆 under density dependence or other specified conditions based on a trajectory exported from RAMAS Metapop:

        library(tidyverse)

# Function for calculating geometric mean
gm_mean <- function(x, na.rm=TRUE){
  exp(sum(log(x[x > 0]), na.rm=na.rm) / length(x))
}

# Function for calculating vector of lambda values
lambda_calc <- function(x) {
  lambda <- numeric()
  for(y in 1:nrow(p_core)){
    lambda[y] <- x$Average[y+1]/x$Average[y]
  }
  return(lambda)
}

# read files
file <- "RAMASoutput/pigs_core_sim.txt"
p_core <- read_tsv(file, skip=14, n_max=11) %>%
    # Change obnoxious column name
    rename(allcols=`Minimum    -1 S.D.    Average    +1 S.D.    Maximum`) %>%
    # because there are a different number of spaces, just want all whitespace to become a bar
    mutate(allcols = str_replace_all(allcols, "[[:space:]]+", "|")) %>% 
    # now separate 
    separate_wider_delim(allcols, 
                         names=c("Time", "Minimum", "lSD", "Average", "hSD", "Maximum"),
                         delim="|") %>%
    # convert caracter columns to numeric
    mutate_if(is.character, as.numeric)

# Calculate lambda
p_core_l <- lambda_calc(p_core)

# Calculate geometric mean lambda
gm_mean(p_core_l)

      3. Note: it is important to use the geometric mean to calculate population growth rate, and not arithmetic mean (R’s mean() function) for an accurate calculation.

9. Conducting a Sensitivity Analysis

  1. The Sensitivity Analysis subprogram allows one to import a metapopulation model and automatically (or manually) adjust values to examine the outcome of different values on the population trajectory. Remember that the simulation values are in PERCENT change. Note: the Sensitivity Analysis program will not allow you to save a session.

    Sensitivity Analysis subprogram

  2. Go to Models > Automatic. This is the window that will allow you to set up the sensitivity analysis.

    • You will need to select a RAMAS Metapopulation file (.mp) to choose as the population that will be modified. Where it says Model file, click the button with three dots and navigate to the desired Metapopulation file.

    • The Parameter drop-down menu allows you to select which parameter will be adjusted with each simulation. We ran a sensitivity analysis of R (maximum growth rates).

    • The No of simulations option allows you to specify how many scenarios to run. The limit is 5, and the boxes below will open up as more scenarios are added.

    • For each scenario (Sim. X \(\pm\) % change:) , enter the percent change you wish to model.

    • We examined 10, -10, 20, -20, 30, -30, 40, and -40% variation in Rmax which required us to run the simulated trajectories in two different sessions.

      Sensitivity analysis for wild pigs in MS

    • Click OK to save and close the window.

  3. Go to Simulation > Run

    • RAMAS will give you a dialog box specifying which scenario will be saved to which file. This cannot be edited. Click OK to run the simulations. It will open new simulation windows as the models run.

      Click Yes to run the simulations

    • When the simulations have finished, another new window will open, again stating the new files. Click OK.

  4. Results cannot be viewed in the Sensitivity analysis program. Close this.

10. Comparing simulation results

  1. The RAMAS Comparison of Results subprogram allows you to import models from the Metapopulation subprogram to visualize and compare results of different scenarios. The comparison of results subprogram can take any Metapop model, not necessarily from sensitivity analysis.

  2. If you open the Comparison of Results subprogram after running a sensitivity analysis, it should automatically load the models generated by Sensitivity Analysis. However, you can add files manually (e.g., if just comparing different models that were created using Metapopulation and not Sensitivity Analysis, such as core, marginal, and highly marginal patch models). Click on the Open symbol to select files. You will need to click Add to navigate and select models to add.

    Comparison of Results subprogram starts with a blank canvas

  3. Once the models are loaded, it will show a summary of each in the main window. If comparing results of a sensitivity analysis, each file will be annotated with the sensitivity conditions.

    Examples of comparing 5 scenarios from a sensitivity analysis

  4. The results menu is the same as for the Metapopulation model, but it will show all of the selected models instead of a single trajectory. You can click the Text tab to view or save the simulated abundance for each scenario. For each simulation, we copied the results into a .txt file so that they could be read into R.

    Trajectories of core, marginal, and highly marginal patch models