r.pi.energy
Individual-based dispersal model for connectivity analysis - energy based.
r.pi.energy [-abdi] input=name [costmap=string] [suitability=string] output=name [out_immi=string] [immi_matrix=string] [mig_matrix=string] [binary_matrix=string] [threshold=float] keyval=integer step_length=integer [step_range=float] [perception=integer] [multiplicator=float] n=integer energy=float percent=float [out_freq=integer] [title="phrase"] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.pi.energy input=name output=name keyval=integer step_length=integer n=integer energy=float percent=float
grass.script.run_command("r.pi.energy", input, costmap=None, suitability=None, output, out_immi=None, immi_matrix=None, mig_matrix=None, binary_matrix=None, threshold=None, keyval, step_length, step_range=None, perception=None, multiplicator=None, n, energy, percent, out_freq=None, title=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("r.pi.energy", input="name", output="name", keyval=integer, step_length=integer, n=integer, energy=float, percent=float)
Parameters
input=name [required]
Name of input raster map
costmap=string
Name of the costmap
suitability=string
Name of the suitability raster with values from 0-100
output=name [required]
Name for output raster map
out_immi=string
Name of the optional raster file for patch immigrants count
immi_matrix=string
Name for immigrants matrix ASCII-file
mig_matrix=string
Name for migrants matrix ASCII-file
binary_matrix=string
Name for binary immigrants(migrants) matrix ASCII-file
threshold=float
Percentage of individuals which must have immigrated(migrated) successfully to be considered for the binary immigrants(migrants) matrix
keyval=integer [required]
Category value of the patches
step_length=integer [required]
Length of a single step measured in pixels
step_range=float
Range to choose the next step direction from, in degrees [default = 180°]
perception=integer
Perception range
multiplicator=float
Attractivity of patches [1-inf]
n=integer [required]
Number of individuals
energy=float [required]
Initial energy of the individuals
percent=float [required]
Percentage of finished individuals desired before simulation ends
out_freq=integer
Output an intermediate state of simulation each [out_freq] steps
title="phrase"
Title for resultant raster map
-a
Set for 8 cell-neighbors. 4 cell-neighbors are default
-b
Set if individuals should be set back after leaving area
-d
Output diversity map
-i
Output Shannon- and Simpson-index
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
input : str, required
Name of input raster map
Used as: input, raster, name
costmap : str, optional
Name of the costmap
Used as: input, raster
suitability : str, optional
Name of the suitability raster with values from 0-100
Used as: input, raster
output : str, required
Name for output raster map
Used as: output, raster, name
out_immi : str, optional
Name of the optional raster file for patch immigrants count
Used as: output, raster
immi_matrix : str, optional
Name for immigrants matrix ASCII-file
Used as: output
mig_matrix : str, optional
Name for migrants matrix ASCII-file
Used as: output
binary_matrix : str, optional
Name for binary immigrants(migrants) matrix ASCII-file
Used as: output
threshold : float, optional
Percentage of individuals which must have immigrated(migrated) successfully to be considered for the binary immigrants(migrants) matrix
keyval : int, required
Category value of the patches
step_length : int, required
Length of a single step measured in pixels
step_range : float, optional
Range to choose the next step direction from, in degrees [default = 180°]
perception : int, optional
Perception range
multiplicator : float, optional
Attractivity of patches [1-inf]
n : int, required
Number of individuals
energy : float, required
Initial energy of the individuals
percent : float, required
Percentage of finished individuals desired before simulation ends
out_freq : int, optional
Output an intermediate state of simulation each [out_freq] steps
title : str, optional
Title for resultant raster map
Used as: "phrase"
flags : str, optional
Allowed values: a, b, d, i
a
Set for 8 cell-neighbors. 4 cell-neighbors are default
b
Set if individuals should be set back after leaving area
d
Output diversity map
i
Output Shannon- and Simpson-index
overwrite: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
Isolation or connectivity of singular patches of a defined landcover class using individual-based dispersal models. This function is based on a maximum amount of energy for each individuals dispersing through the landscape which is deminished by a fricition or cost map. Unlike the related function r.pi.energy does this function allows individuals to stay or move within a patch until the energy is depleted.
NOTES
Amount of successful immigrants or emigrants are not taken individual into account which emigrated from and immigrated into the same patch (pseudo immigration).
The suitability matrix impacts the step direction, while the costmap relates to the depletion of assigned energy.
If individuals are moving beyond the mapset borders the indivuals are set back to their original source patches.
EXAMPLE
An example for the North Carolina sample dataset: The amount of successful emigrants (*_emi), immigrants (*_imi), the percentage of immigrants per patch (*_imi_percent), the amount of lost indivuals (*_lost), the amount of migrants (*_mig), successful (*_mig_succ) and unsuccessful migrants (_mig_unsucc) can be retrieved using this command:
r.pi.energy input=landclass96 output=energy1 keyval=5 n=1000 step_length=5 energy=10 percent=80
introducing costs for movement results in different immigration counts:
r.mapcalc "cost_raster = if(landclass96==5,1,if(landclass96 == 1, 10, if (landclass96==3,2, if(landclass96==4,1,if(landclass96==6,100)))))"
r.pi.energy input=landclass96 output=energy1 keyval=5 n=1000 step_length=5 energy=10 percent=80 costmap=cost_raster
introducing a suitability for the movement:
# the suitability for the next step selection is defined as: class 5
# and 3 (forest and grassland) have a high suitability, while shrubland
# (class 4) only a moderate and water and developed areas (class 6 and 1)
# have a very low suitability:
r.mapcalc "suit_raster = if(landclass96==5,100,if(landclass96 == 3, 100, if (landclass96==1,1, if(landclass96==6,1,if(landclass96==4,50)))))"
r.pi.energy input=landclass96 output=energyiter3 keyval=5 n=1000 step_length=5 energy=10 percent=80 suitability=suit_raster
further settings can be changed and information retrieved: setting the perception range to 10 pixel:
r.pi.energy input=landclass96 output=energyiter keyval=5 n=1000 step_length=5 energy=10 percent=80 perception=10
increasing the attraction to move towards patches to 10:
r.pi.energy input=landclass96 output=energyiter keyval=5 n=1000 step_length=5 energy=10 percent=80 stats=average multiplicator=10
output of each movement location for a defined step frequency. Here every 10th step is provided as output raster:
r.pi.energy input=landclass96 output=energyiter keyval=5 n=1000 step_length=5 energy=10 percent=80 stats=average out_freq=10
SEE ALSO
r.pi.energy.pr, r.pi.energy, r.pi
AUTHORS
Programming: Elshad Shirinov
Scientific concept: Dr. Martin Wegmann
Department of Remote Sensing
Remote Sensing and Biodiversity Unit
University of Wuerzburg, Germany
Port to GRASS GIS 7: Markus Metz
SOURCE CODE
Available at: r.pi.energy source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819