Skip to content

r.pi.import

Import and generation of patch raster data

r.pi.import [-a] input=string raster=name output=name keyval=integer id_col=integer val_col=integer [title="phrase"] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.pi.import input=string raster=name output=name keyval=0 id_col=0 val_col=0

grass.script.run_command("r.pi.import", input, raster, output, keyval, id_col, val_col, title=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.pi.import", input="string", raster="name", output="name", keyval=0, id_col=0, val_col=0)

grass.tools.Tools.r_pi_import(input, raster, output, keyval, id_col, val_col, title=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_pi_import(input="string", raster="name", output="name", keyval=0, id_col=0, val_col=0)

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

input=string [required]
    Name of the input ASCII-file
raster=name [required]
    Name of input raster map
output=name [required]
    Name for output raster map
keyval=integer [required]
    Category value of the patches
id_col=integer [required]
    Number of the column with patch IDs
val_col=integer [required]
    Number of the column with patch values
title="phrase"
    Title for resultant raster map
-a
    Set for 8 cell-neighbors. 4 cell-neighbors are default
--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 the input ASCII-file
    Used as: input
raster : str, required
    Name of input raster map
    Used as: input, raster, name
output : str, required
    Name for output raster map
    Used as: output, raster, name
keyval : int, required
    Category value of the patches
id_col : int, required
    Number of the column with patch IDs
val_col : int, required
    Number of the column with patch values
title : str, optional
    Title for resultant raster map
    Used as: "phrase"
flags : str, optional
    Allowed values: a
    a
        Set for 8 cell-neighbors. 4 cell-neighbors are default
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

input : str | io.StringIO, required
    Name of the input ASCII-file
    Used as: input
raster : str | np.ndarray, required
    Name of input raster map
    Used as: input, raster, name
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Name for output raster map
    Used as: output, raster, name
keyval : int, required
    Category value of the patches
id_col : int, required
    Number of the column with patch IDs
val_col : int, required
    Number of the column with patch values
title : str, optional
    Title for resultant raster map
    Used as: "phrase"
flags : str, optional
    Allowed values: a
    a
        Set for 8 cell-neighbors. 4 cell-neighbors are default
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

DESCRIPTION

Import and generation of patch raster data based on individual patch based raster data.

NOTES

...

EXAMPLE

An example for the North Carolina sample dataset: In order to run r.pi.import we need an exported patch index raster:

r.pi.index input=landclass96 output=landclass96_forestclass5_area keyval=5 method=area

export this resulting map:

r.pi.export input=landclass96_forestclass5_area output=patch_area_out values=patch_area_values id_raster=forestclass5_ID stats=average,variance,min

modify it with R or just import the file again and assign the percentage coverage to each fragment. You need the patch_area_values file and the previously used input file forestclass96 raster (important: the same patch coverage is mandatory otherwise patch ID in the text file and raster are not congruent!):

r.pi.import input=patch_area_values raster=landclass96 output=imported_values keyval=5 id_col=1 val_col=2

if you want to export the patch values to R and do e.g. a linear regression of two patch values and import them again in GRASS, do:
apply r.pi.export with two indices (A and B), in R, do:

resid.AB <- resid(lm(A[,3]~B[,3])) #write residuals of a linear regression
df.resid.AB <- data.frame(A[,1],resid.AB) #merge patch IDs and resid into same data frame
write.table(df.resid.AB,"resid.for.GRASS",row.names=F,col.names=F)

exit R and run in GRASS:

r.pi.import input=resid.for.GRASS raster=landclass96 output=resid.AB keyval=5 id_col=1 val_col=2

SEE ALSO

r.pi.export, 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.import source code (history)
Latest change: Thursday Mar 20 21:36:57 2025 in commit 7286ecf