r.pi.searchtime

Individual-based dispersal model for connectivity analysis (time-based)

Command linePython (grass.script)

r.pi.searchtime [-acdi] input=name [suitability=string] output=name [out_immi=string] [immi_matrix=string] [binary_matrix=string] [threshold=float] keyval=integer step_length=integer [step_range=float] [perception=integer] [multiplicator=float] n=integer percent=float stats=string [,string,...] [maxsteps=integer] [out_freq=integer] [title="phrase"] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.pi.searchtime input=name output=name keyval=integer step_length=integer n=integer percent=float stats=string

grass.script.run_command("r.pi.searchtime", input, suitability=None, output, out_immi=None, immi_matrix=None, binary_matrix=None, threshold=None, keyval, step_length, step_range=None, perception=None, multiplicator=None, n, percent, stats, maxsteps=None, out_freq=None, title=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.pi.searchtime", input="name", output="name", keyval=integer, step_length=integer, n=integer, percent=float, stats="string")

Parameters

Command linePython (grass.script)

input=name [required]
    Name of input raster map
suitability=string
    Name of the costmap 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
binary_matrix=string
    Name for binary immigrants matrix ASCII-file
threshold=float
    Percentage of individuals which must have immigrated successfully to be considered for the binary immigrants 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
percent=float [required]
    Percentage of individuals which must have arrived successfully to stop the model-run
stats=string [,string,...] [required]
    Statistical method to perform on the values
    Allowed values: average, variance, standard deviation, median, min, max
maxsteps=integer
    Maximum steps for each individual
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
-c
    Include cost of the path in the calculation of steps
-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
suitability : str, optional
    Name of the costmap 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
binary_matrix : str, optional
    Name for binary immigrants matrix ASCII-file
    Used as: output
threshold : float, optional
    Percentage of individuals which must have immigrated successfully to be considered for the binary immigrants 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
percent : float, required
    Percentage of individuals which must have arrived successfully to stop the model-run
stats : str | list[str], required
    Statistical method to perform on the values
    Allowed values: average, variance, standard deviation, median, min, max
maxsteps : int, optional
    Maximum steps for each individual
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, c, d, i
    a
        Set for 8 cell-neighbors. 4 cell-neighbors are default
    c
        Include cost of the path in the calculation of steps
    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

Individual-based dispersal model for connectivity analysis (time-based)

This module provides information about the isolation or connectivity of individual fragments derived of a landcover classification. Unlike r.pi.energy this module provides information about the time from emigration to immigration. The individual based dispersal model results are based on the step length and range, the perception distance and the attractivity to move towards patches.

NOTES

The suitability matrix impacts the step direction of individuals. 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 connectivity of patches of the landclass96 class 5 are computed using the time from emigration to immigration. The step length is set to 5 pixel, the output statistics are set to average time and variance of searchtime. For each patch 1000 individuals were released and the model stopped when at least 80% of all individuals sucessfully immigrated:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000

constrain the angle of forward movement to 10 degrees:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 step_range=10

setting the perception range to 10 pixel:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 perception=10

increasing the attraction to move towards patches to 10:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 multiplicator=10

limiting the amount of steps to 10:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 maxsteps=10

output of each movement location for a defined step frequency. Here every 10th step is provided as output raster:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 out_freq=10

output of a raster which immigration counts:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 out_immi=immi_counts

output of a binary immigration matrix. Each patch emigration and immigration for all patch combinations is recorded as 0 or 1:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 binary_matrix=binary_matrix.txt

output of a matrix with immigration counts for each patch:

r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 immi_matrix=immi_counts.txt

the previous examples assumed a homogeneous matrix, a heterogenous matrix can be included using a raster file which values are taken as costs for movement (0-100):

# it is assumed that our species is a forest species and cannot move
# through water, hence a cost of 100, does not like urban areas
# (class: 6, cost: 10) but can disperse through shrubland (class 4,
# cost=1) better than through grassland (class 3, cost: 2):

r.mapcalc "suit_raster = if(landclass96==5,1,if(landclass96 == 1, 10, if (landclass96==3,2, if(landclass96==4,1,if(landclass96==6,100)))))"
r.pi.searchtime input=landclass96 output=searchtime1 keyval=5 step_length=5 stats=average,variance percent=80 n=1000 suitability=suit_raster

SEE ALSO

r.pi.searchtime.pr, r.pi.searchtime.mw, 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.searchtime source code (history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819