NetLogo banner

NetLogo Publications
Contact Us

Modeling Commons

Beginners Interactive NetLogo Dictionary (BIND)
NetLogo Dictionary

User Manuals:
Farsi / Persian


NetLogo User Community Models

(back to the NetLogo User Community Models)

[screen shot]

If clicking does not initiate a download, try right clicking or control clicking and choosing "Save" or "Download".(The run link is disabled because this model uses extensions.)


We developed a simulation model ("TraitScape") that simulates dynamics of hypothetical species in hypothetical landscapes. For a given species type (characterized by a fully factorial set of species parameters, see "input parameter values that were experimentally varied"), we conducted multiple simulation runs, each in a different landscape. We then analyzed the set of runs to determine the scale of effect of landscape structure on population abundance for that species type. To make our results as useful as possible for field researchers, we constructed the simulations such that the output data were the same as what would be collected by field ecologists conducting a "focal patch" landscape-scale study (Brennan et al. 2002), i.e., where the response variable (e.g. population abundance) is measured at the centers of multiple sites and the predictors are landscape structure variables (e.g. habitat amount) measured in the landscapes surrounding the focal sites. By conducting multiple sets of simulations, with different values for the parameters that determine species type, we tested the predictions that dispersal distance, reproductive rate, and movement behavior should influence the scale of effect of the landscape, and we quantified their effects. In addition, we used information concerning secondary outcomes (e.g. population size, shape of dispersal kernel, variation among runs in average dispersal distances) collected from each treatment combination to explore the mechanisms linking dispersal distance, reproductive rate, and movement behavior to scale of effect.

authors: Heather Bird Jackson and Lenore Fahrig


This program allows an investigator to test hypotheses concerning the effect of three species traits (dispersal distance, reproductive rate, and movement behavior) on abundance within a focal area. The output includes information about habitat cover in 10 concentric rings and abundance of individuals in the focal area. These data can be used to calculate the scale of effect, or the distance from the center of a focal area at which habitat cover is most associated with abundance in the focal area.


Model Description

TraitScape is an individual-based spatially-explicit model.

In TraitScape, individuals represent generic mobile animals and are defined by four state variables: original position (x0, y0), current position (x, y), age (0 or 1), and energy level (lifetime number of movement steps possible). Original position and energy are determined at birth, current position is updated after each movement step, and age is updated once a year.

Default simulations are run in a 127 X 127 grid with reflective boundaries (see "other input parameters that can be adjusted in procedures"). This grid size is large enough to allow ten potential scales of effect (concentric radii from 9-63 cells), but small enough to keep the global population at a computationally manageable size (generally < 20,000 individuals). The odd number of cells (127 X 127) is an artifact of the midpoint displacement algorithm (Saupe 1988) which is used to generate naturalistic random landscapes (see “Submodels”). Grid cell size does not represent an absolute spatial unit (e.g. meters); instead, the size of grid cells is only meaningful with respect to the step size of individuals which can vary with user input. Grid cells are the finest grain at which habitat type is categorized. Density-dependence in reproduction and settlement (when applicable) is modeled within grid cells.

Grid cells are classified as either suitable habitat (hereafter “habitat”) or unsuitable habitat (hereafter “matrix”). To simplify our model, we did not explicitly model mortality during movement, whether in matrix or habitat. All adults die at the end of reproduction. Therefore, if an individual settles in the matrix it dies without reproducing. Individuals with informed movement behavior (see "Input parameter values that can be experimentally varied") are responsive to cell type during settlement and/or movement, and are consequently less likely to settle in matrix.

The model proceeds in time steps, which we call "years" and which are equivalent to generations. In order to allow populations to stabilize, each run lasts up to 5000 years. Most runs are much shorter because a run is ended when the global population size reaches a steady state (i.e. if population size varies by less than 10% from decade to decade for at least 10 decades) or when the global population goes extinct.
TraitScape simulates the yearly processes of adult death, juvenile movement (which ends in maturation), and adult reproduction, in that order. Each process is completed before the next process begins. Within each process, each individual fully completes its action (e.g. movement) before the next randomly selected individual initiates action. Within years, time is not explicitly represented; instead each process continues until completion and then the next process immediately begins.



An individual simulation run begins by setting up a random landscape using the midpoint displacement algorithm (Saupe 1988). This algorithm produces realistic-looking landscapes and allows independent control of the amount of habitat and the configuration of habitat (for examples see Saupe 1988; With and King 1999). The algorithm creates fractal landscapes which can vary in the amount of spatial autocorrelation according to the parameter H. The fractal dimension (D) of the landscape is a property of H such that D = 3 - H. The main difference among landscapes in our runs is the amount of habitat, not the configuration of habitat. H is held constant at 0.5 (moderate spatial autocorrelation, see "other input parameters that can be adjusted in procedures"), but the amount of habitat is randomly selected at the beginning of each run from a uniform distribution between 5% and 95%.

Once a random landscape is generated, a focal area is added to its center. The focal area is the sampling area within which population abundance is sampled. To keep local conditions constant among runs, the focal area is always 100% habitat. Its radius is 7 cells (see "other input parameters that can be adjusted in procedures").

At the beginning of a simulation run, individuals are placed randomly in the landscape; runs begin with 1612 individuals (1 for every ten grid cells, see "other input parameters that can be adjusted in procedures"). Random distribution of individuals without regard for habitat ensures that the initial density of individuals in breeding habitat is independent of the amount of habitat in the landscape (Fahrig 2001). All starting individuals are juveniles. After initial setup, the model runs on a yearly time step with four main submodels: adult death, juvenile movement, and adult reproduction.

Adult Death

At the beginning of each year, all adults die (see "other input parameters that can be adjusted in procedures").

Juvenile Movement

Movement is modeled one individual at a time. Each individual takes successive steps until settlement occurs. Before each step, an exploratory loop cycles through possible steps until an acceptable step (i.e. one in which no forbidden steps are made) is randomly drawn. A step outside of the grid is always forbidden. With DHSG, a step into the matrix is always forbidden.

Like many animals (Kareiva and Shigesada 1983), model individuals move according to a correlated random walk. In a correlated random walk subsequent movement directions are correlated such that highly correlated movement paths are nearly straight (Turchin 1998). In the model, the initial direction of movement for each individual is selected randomly from between 0 and 2? radians. Thereafter, the direction of a step is drawn from a wrapped Cauchy distribution with a mean direction equal to the previous direction (see "other input parameters that can be adjusted in procedures", Fletcher 2006). The concentration around the mean direction is determined by ?, where ?=0 results in a random walk and ?=1 results in a perfectly straight line. For our simulations, we fixed ? at 0.90 (nearly straight) which is close to the optimal linearity for finding new habitat (Barton et al. 2009; Fletcher 2006; Zollner and Lima 1999, see "other input parameters that can be adjusted in procedures").

Each step length is drawn from a negative exponential distribution with a mean determined by the experimental treatment (range = 0.1 – 15.0 cells, see "Input parameter values that can be experimentally varied"). We manipulated average dispersal distances by altering step length rather than number of steps because theory suggests that body size is associated with space use (e.g. home range size) via its influence on step size or sampling scale (Jetz et al. 2004; Ritchie 2010).

After a step is taken, an individual considers settlement (the end of dispersal). The choice to settle depends on (a) the number of steps already taken and, for most treatments, (b) the conditions in the cell. The maximum number of steps possible for each individual is assigned at birth, and an individual must settle once the maximum number of steps has been reached even if it is in matrix. The number of steps is drawn from a negative-exponential distribution with a mean of 9 for all runs in our simulations. With RS, the only reason an individual settles is that it has reached the maximum number of steps assigned at birth, but in other treatments, conditions in the cell can cause movement to stop earlier. With HS, individuals stop at the first habitat cell they encounter. With DHS and DHSG, individuals stop at the first habitat cell they encounter that is not occupied by another individual. Once an individual has settled, its status is changed from juvenile to adult and it no longer has the opportunity to move.

Both step size and number of steps are drawn from negative exponential distributions to produce negative-exponentially distributed dispersal distances (straight-line distance between origin and settlement). A negative-exponential distribution is a common method used to model “fat-tailed” dispersal, or more long-distance dispersal than expected under a Gaussian distribution (e.g. Chapman et al. 2007; Kot et al. 1996). Fat-tailed dispersal is exhibited by many species in nature (Okubo 1980; Turchin 1998).


If settled in habitat, an adult has the opportunity to reproduce, with the number of offspring governed by logistic growth (see also Barton et al. 2009). The number of offspring per individual is drawn from a Poisson distribution (the distribution commonly used for simulating stochastic fecundity, Akçakaya 1991) with a mean determined by reproductive rate, the carrying capacity for a cell (k = 2 in our runs), and the density of individuals within a cell (see "Input parameter values that can be experimentally varied")


Focal area: Survey area at center of landscape which consists of 100% breeding habitat.
Not necessarily a "patch" in the metapopulation sense because it may or may not be
isolated from breeding habitat. Rather, the focal area is simply the area within which
population processes are scrutinized. This area is colored dark pink at the center of the landscape.

Scale of effect: The size of the landscape from the perspective of the focal population, i.e. the distance from the center of a focal area at which habitat cover is most associated with abundance in the focal area. The scale of effect is not calculated in this program, but should instead be calculated using the output. To find the scale at which habitat cover is most associated with abundance in the focal area, one can calculate one of three measures of fit between abundance in the focal area and habitat cover at each scale: 1) the correlation coefficient, 2) the coefficient of determination (R-squared), or 3) AIC (Akaike's Information Criterion).


Movement step size (habstep): Determines the average step size for each move. The length of each step is drawn from a random exponential distribution with a mean of "habstep".

Reproductive rate (growth): The average number of offspring per individual.Individuals are asexual in this model. The actual number of births is drawn from a Poisson distribution with a mean that is determined by growth/[1 + Na*(growth + 1)/habk], where Na is the number of adults in a cell and habk is the carrying capacity of a cell (held constant at 2). This model assumes contest competition.

Movement behavior (settlerule and matprob): The rules that guide settlement and movement of individuals. There are three possible settlement rules: "random", "habitat", and "empty habitat". "Random" dispersers do not stop moving until they have moved the maximum number of moves (energy - a value assigned at birth and drawn from an exponential distribution with mean of 9). "Habitat" dispersers settle in the first habitat cell encountered during dispersal. "Empty habitat" dispersers settle in the first habitat cell encountered that is not occupied by an adult. Matprob is a continuous variable that determines the probability that an individual will accept a possible step into the matrix. Matprob = 0 makes all individuals completely gap-avoidant, whereas matprob = 1 makes all individuals completely insensitive to gaps during movement.

Habitat cover (inputs: user-cover, vary-cover?): Proportion of landscape cells which are breeding habitat. The default is for the program to randomly select the amount of cover from between 0.05 and 0.95. The user can control habitat cover by setting vary-cover? to NO, and adjusting user-cover to the desired amount.


Landscape size: the size of a landscape can be adjusted manually on the Interface. The default is 127 X 127 cells.

Length of run (time, stabledif): Time determines the maximum length of a run. The default is 5000 generations. Runs are stopped earlier if a) global extinction occurs or b) population size varies by less than stabledif (default = 10%) every 10 years for 100 years (time default = 5000, possible values >= 1; stabledif default = 0.1, possible values = 0-1).

Spatial autocorrelation of habitat (H): The degree of clumpiness of habitat cells; The opposite of habitat fragmentation. Given the same habitat cover, low H (as low as 0) will result in many small patches and low interpatch distances, whereas high H (up to 1) will result in a few large patches with high average interpatch distances (default = 0.5, possible values = 0-1).

Size of focal area (focal-patch-radius): The default radius of the focal area is 7 cells (which makes 149 cells total).

Initial ratio of individuals to cells (initialp): the default is 0.1, so that an average of 10% of cells contain an individual at the beginning. Individuals are randomly placed throughout the landscape so that the initial distribution of individuals is independent of habitat.

Average energy level per individual (meansteps): at birth, an energy level (energy) is assigned to each individual. This determines the maximum number of steps that individual will be able to take. This value is drawn from a random exponential distribution with a mean of meansteps (default = 9; possible values >= 1).

Correlation in the direction of successive moves (habCRW, matCRW): Individuals move according to the rules of a correlated random walk (Turchin 1998), which means that the direction of successive moves is correlated. The default correlation between successive directions is 0.9, with no difference in movement whether an individual is in habitat or matrix. The correlation within habitat and matrix can be changed by modifying habCRW and matCRW, respectively (default = 0; possible values = 0-1).

Change in step size in the matrix (deltastep): The average step size in the matrix is calculated by habstep + deltastep. A user could make step sizes different in the matrix by changing deltastep from its default value of 0 (default = 0, possible values = -infinity - infinity).

Variation in step sizes (vary-step?): A user could make all steps the same size by setting vary-step? to FALSE (default = TRUE).

Probability of movement (moveprob): With default setting of moveprob = 1, each individual is assigned to the mover? = TRUE category at birth. This could be varied within the population if moveprob is set to a lower value (default = 1; possible values = 0-1).

Carrying capacity of habitat cells (habk): the carrying capacity of habitat cells can be changed from its default of 2 (possible values >= 1).

Probability of settlement when habitat rules are met (setprob): By default, individuals have a 100% chance of settling if habitat rules are met. This can become more variable by setting setprob to a lower value (default = 1, possible values = 0-1).


Abundance in focal area (N1): the number of adults in the focal area during the most recent post-breeding census.

Dispersal distance (distmed, distmax): Total net displacement, or the straight-line distance between the natal location (x,y) and the settlement location (x,y). The average dispersal distance of individuals in a population can be changed by altering the average step length (habstep on the Interface). The distmed and distmax monitors on the Interface report the median and maximum dispersal distances for all individuals in the entire landscape.

Abundance in entire landscape (nadults): the number of adults in the entire landscape during the post-breeding census. This value is also graphed in the plot above the landscape.

Habitat cover (pcover, c1-c10): The actual amount of cover is reported for the entire landscape (pcover on the Interface monitor), and for the entire area within each concentric ring (c1 - c10 on the Interface monitor).


The outputs in this program are best designed to be used with BehaviorSpace. If the user wants to print outputs without using BehaviorSpace, then save-output? must be set to TRUE on the Interface. Outputs are saved to a .csv file in the "directory" under the file name that is the combination of "filename" and "experiment". The header is printed only when user-run-num is set to 1. *If user-run-num is set to 1, any data previously in the file by the same name will be erased. Change the file name or increase user-run-num to prevent previous data from getting erased.* The output from each run is recorded on a new line. User-run-num can be manually increased by the user in order to number runs, but the output will be printed even if the user-run-num is the same for successive runs.

Inputs are recorded first and most have been described previously. Inputs include: run number (run-num), the coordinates for the corners of the landscape (max-pxcor, max-pycor, min-pxcor, min-pycor), the file name (filename), the experiment name (experiment), whether a map was saved (save-map?), the random number seed used for the run (seed), whether the seed was set by the user (set-seed?), radius of focal area (focal-patch-radius), proportion of cells initially occupied (initialP), radius of the largest concentric circle (radius-max), variation in abundance across decades below which the run is stopped (stabledif), maximum number of generations (time), settings for midpoint displacement algorithm (additions, H, sigma), correlation of successive moves (H), carrying capacity of habitat cells (habk), average step size (habstep), probability of settlement given that settlement rules are met (setprob), are step sizes drawn from a random exponential distribution (vary-step?), reproductive rate (growth), probability that an individual is assigned mover? status at birth (moveprob), change in step size relative to habitat in the matrix (deltastep), correlation in successive moves in the matrix (matCRW), probability that an individual will accept a move into the matrix (matprob).

Outputs are recorded next.

this-seed: the random number seed used for the run

timer: the amount of time (minutes.seconds) that the run ran

;; -------------------- landscape attributes -------------------- ;;

real-cover: the habitat cover randomly assigned to the landscape or by the user

pcover: the actual amount of cover in the landscape (due to the random landscape algorithm, this can be slightly different from the assigned cover)

num-hab-patches: the number of habitat cells in the landscape

real-H: the autocorrelation parameter assigned to habitat cells in the landscape

;; -------------------- attributes of the global population -------------------- ;;

nadults_10yr: the average number of adults in the entire landscape over the last 10 years

nadults: the number of adults in the entire landscape in the last year

nmove: the number of adults that moved to a different cell from their natal cell in the last year

nfail: the number of adults that moved from their natal cell and settled in matrix

nsucc: the number of adults that moved from their natal cell and settled in habitat

psucc: the proportion of adults that moved from their natal cell and settled in habitat

dist series: the distribution of dispersal distances of the entire population (distmin = minimum, dist02.5 = 2.5th percentile, dist25 = 25th percentile, distmed = median, dist75 = 75th percentile, dist97.5 = 97.5th percentile, distmax = maximum distance, distmean = mean distance, hcoef = whiskers on a boxplot based on Tukey (1977))

time series: the distribution of steps, i.e. the number of steps taken by individuals before settlement (timemin = minimum, time02.5 = 2.5th percentile, time25 = 25th percentile, timemed = median, time75 = 75th percentile, time97.5 = 97.5th percentile, timemax = maximum, timemean = mean)

;; -------------------- attributes of the focal population -------------------- ;;

N_10yr: the average number of adults in the focal population for the last 10 years

N1: the number of adults in the focal population in the last year

I1: the number of adult immigrants into the focal population in the last year

O1: presence of adults in the focal area in the last year

B0: the number of juveniles in the focal area in the last year

B0t-1: the number of juveniles in the focal area in the second to the last year

D1: the number of individuals born in the focal area that moved out of the focal area and landed in matrix this year

E1: the number of adults born in the focal area that moved out of the focal area and landed in habitat this year

S1: the number of adults born in the focal area that stayed in the focal area this year

Idist series: Dispersal distances of individuals that immigrated into the focal area (Idist25 = 25th percentile, Idistmed = 50th percentile, Idist75 = 75th percentile, Idistmax = maximum, Ihcoef = whiskers on a boxplot based on Tukey (1977)).

;; -------------------- attributes of focal area -------------------- ;;

r1-r10: the radii of each concentric ring surrounding the focal area

c1-c10: the proportion habitat cover in each concentric buffer surrounding the focal area

g1-g10: the average gap size in each concentric buffer surrounding the focal area. This is calculated by measuring gaps in two transects: 1) top to bottom and intersecting with the center of the focal area, 2) left to right and intersecting with the center of the focal area.


Akçakaya HR (1991) A method for simulating demographic stochasticity. Ecological Modelling 54: 133-136

Barton KA, Phillips BL, Morales JM and Travis JMJ (2009) The evolution of an 'intelligent' dispersal strategy: biased, correlated random walks in patchy landscapes. Oikos 118: 309-319

Chapman DS, Dytham C and Oxford GS (2007) Modelling population redistribution in a leaf beetle: an evaluation of alternative dispersal functions. Journal of Animal Ecology 76: 36-44

Fahrig L (2001) How much habitat is enough? Biological Conservation 100: 65-74

Fletcher RJ (2006) Emergent properties of conspecific attraction in fragmented landscapes. American Naturalist 168: 207-219

Jetz W, Carbone C, Fulford J and Brown JH (2004) The scaling of animal space use. Science 306: 266-268

Kareiva PM and Shigesada N (1983) Analyzing insect movement as a correlated random-walk. Oecologia 56: 234-238

Kot M, Lewis MA and van den Driessche P (1996) Dispersal data and the spread of invading organisms. Ecology 77: 2027-2042

Okubo A (1980) Diffusion and ecological problems: mathematical models. Springer-Verlag, New York

Ritchie ME (2010) Scale, Heterogeneity, and the Structure and Diversity of Ecological Communities. Princeton University Press, Princeton, NJ

Saupe D (1988) Algorithms for random fractals. In Peitgen H.-O. and Saupe D. (eds.), The science of fractal images, pp. 71-113. Springer-Verlag, New York

Turchin P (1998) Quantitative Analysis of Movement: Measuring and Modeling Population Redistribution in Animals and Plants. Sinauer Associates, Inc., Sunderland, Massachusetts

With KA and King AW (1999) Extinction thresholds for species in fractal landscapes. Conservation Biology 13: 314-326

Zollner PA and Lima SL (1999) Search strategies for landscape-level interpatch movements. Ecology 80: 1019-1030


If you mention this model in an academic publication, we ask that you include these citations for the model itself and for the NetLogo software:

- Jackson, HB, Fahrig L (in press). What size is a biologically relevant landscape? Landscape Ecology

- Wilensky, U. (1999). NetLogo. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.

In other publications, please use:
- Copyright 2012 Heather Bird Jackson. All rights reserved.


Copyright 2012 Heather Bird Jackson. All rights reserved.

Permission to use, modify or redistribute this model is hereby granted, provided that both of the following requirements are followed:
a) this copyright notice is included.
b) this model will not be redistributed for profit without permission from Heather Bird Jackson.

(back to the NetLogo User Community Models)