GRASS-Wiki - User contributions [en]

GRASS Python Scripting Library

2018-02-09T12:55:47Z

⚠️BernardoBrenoPacas: detail regarding del_temp_region

{{Python}}
Python API documentation:

* [http://grass.osgeo.org/grass70/manuals/libpython/ Python API for GRASS GIS 7] and [http://grass.osgeo.org/grass70/manuals/libpython/script_intro.html Python Scripting Library]
* [http://grass.osgeo.org/programming6/pythonlib.html for GRASS GIS 6]: core.py, db.py, raster.py, vector.py, setup.py, array.py task.py

The GRASS Python Scripting Library can be imported by statement

<source lang=python>
import grass.script as gscript
</source>

The other packages such as PyGRASS can be imported in a similar way.

The code in {{src|lib/python/|lib/python}} provides <tt>grass.script</tt> and other packages in order to support GRASS scripts written in Python. The {{src|scripts}} directory of GRASS GIS 7 contains a series of examples actually provided to the end users (while the script in GRASS GIS 6 are shell scripts).

For more general info, see also [[GRASS and Python]] and see also [[Converting Bash scripts to Python]] if you have some Bash scripts you want to rewrite to Python.

== Uses for read, feed and pipe, start and exec commands ==

All of the <tt>*_command</tt> functions use {{pyapi|script|script.core|make_command}} to construct a command
line for a program which uses the {{cmd|g.parser|desc=GRASS parser}}. Most of them then pass
that command line to <tt>subprocess.Popen()</tt> via {{pyapi|script|script.core|start_command}}, except
for {{pyapi|script|script.core|exec_command}} which uses <tt>os.execvpe()</tt>.

[To be precise, they use <tt>grass.Popen()</tt>, which just calls
<tt>subprocess.Popen()</tt> with 'shell=True' on Windows and 'shell=False'
otherwise. On Windows, you need to use 'shell=True' to be able to
execute scripts (including batch files); 'shell=False' only works with
binary executables.]

{{pyapi|script|script.core|start_command}} separates the arguments into those which
<tt>subprocess.Popen()</tt> understands and the rest. The rest are passed to
<tt>make_command()</tt> to construct a command line which is passed as the
"args" parameter to <tt>subprocess.Popen()</tt>.

In other words, {{pyapi|script|script.core|start_command}} is a GRASS-oriented interface to
<tt>subprocess.Popen()</tt>. It should be suitable for any situation where you
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is {{cmd|r.mapcalc}} in 6.x).

Most of the others are convenience wrappers around <tt>start_command()</tt>, for common use cases.

* {{pyapi|script|script.core|run_command}} calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to <tt>system()</tt>.

* {{pyapi|script|script.core|pipe_command}} calls <tt>start_command()</tt> with 'stdout=PIPE' and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").

* {{pyapi|script|script.core|feed_command}} calls <tt>start_command()</tt> with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")

* {{pyapi|script|script.core|read_command}} calls <tt>pipe_command()</tt>, reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.

* {{pyapi|script|script.core|write_command}} calls <tt>feed_command()</tt>, sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".

* {{pyapi|script|script.core|parse_command}} calls <tt>read_command()</tt> and parses its output as key-value pairs. Useful for obtaining information from {{cmd|g.region}}, {{cmd|g.proj}}, {{cmd|r.info}}, etc.

* {{pyapi|script|script.core|exec_command}} doesn't use <tt>start_command()</tt> but <tt>os.execvpe()</tt>. This causes the specified command to replace the current program (i.e. the Python script), so <tt>exec_command()</tt> never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step. Notes: exec_command() is rarely appropriate. You probably want run_command() instead. On Windows, exec_command() will probably require the ".exe" suffix.

If you have any other questions, you might want to look at the code ({{src|lib/python/core.py}}). Most of these functions are only a few lines long.

=== Hints for parse_command() ===

To turn this command
g.rename rast=old_name,new_name
into a g.parse_command() call, you need to consider that it is a function call with three arguments:
# "g.rename"
# rast=old_name
# new_name

The second argument is a keyword argument, the first and third are
positional (non-keyword) arguments. Python doesn't allow positional
arguments to follow keyword arguments; positional arguments come
first, keyword arguments last.

Given the context, it's safe to assume that you want to pass a pair of
map names as the value to the rast= option. This requires explicit
parentheses so that the comma is treated as forming a tuple rather
than as an argument separator:

g.parse_command("g.rename", rast=(old_name,new_name))

The parentheses in a tuple value can only be omitted if it doesn't
result in the comma being ambiguous (as is the case in a function
call).

== Interfacing ==

=== Interfacing with NumPy ===

The {{pyapi|script|script.array|array}} module defines a <code>class array</code> which is a subclass of [http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html numpy.memmap] with <code>.read()</code> and <code>.write()</code> methods to read/write the underlying file via {{cmd|r.out.bin}}/{{cmd|r.in.bin}}. Metadata can be read with {{pyapi|script|script.raster|raster_info}}:

Example:

<source lang="python">
import grass.script as grass
import grass.script.array as garray

def main():
map = "elevation.dem"

# read map
a = garray.array()
a.read(map)

# get raster map info
print grass.raster_info(map)['datatype']
i = grass.raster_info(map)

# get computational region info
c = grass.region()
print "rows: %d" % c['rows']
print "cols: %d" % c['cols']

# new array for result
b = garray.array()
# calculate new map from input map and store as GRASS raster map
b[...] = (a / 50).astype(int) * 50
b.write("elev.50m")
</source>

The size of the array is taken from the current region ([[computational region]]).

The main drawback of using numpy is that you're limited by available
memory. Using a subclass of <code>numpy.memmap</code> lets you use files which may
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.

'''NULL (no data) management:'''

For integer maps, the NULL value is -2^31 = -2147483648. For floating-point maps, the NULL value is NaN. Note that the null= parameter for read() and write() specifies the value in the numpy array which is mapped to/from null values in the GRASS raster map.

If you're using floating-point numpy arrays, then use (Note: This assumes that atof() and sscanf("%lf") recognise "nan"; this is the case on Linux, but doesn't appear to work on Windows)
null=numpy.nan

For integer arrays, using
null=-2147483648
will ensure that valid values don't collide with NYLLs.

'''MASK support:'''

The function grass.script.array.read() and ...write() use r.out.bin and r.in.bin respectively. r.out.bin respects the MASK.

=== Interfacing with NumPy and SciPy ===

[http://docs.scipy.org/doc/scipy/reference/index.html SciPy] offers simple access to complex calculations. Example:

<source lang="python">
from scipy import stats
import grass.script as grass
import grass.script.array as garray

def main():
map = "elevation.dem"

x = garray.array()
x.read(map)

# Descriptive Statistics:
print "max, min, mean, var:"
print x.max(), x.min(), x.mean(), x.var()
print "Skewness test: z-score and 2-sided p-value:"
print stats.skewtest(stats.skew(x))
</source>

=== Interfacing with NumPy, SciPy and Matlab ===

One may also use the SciPy - Matlab interface:

r.out.mat input=elevation output=elev.mat

<source lang="python">
### PY ###
import scipy.io as sio
# load data
elev = sio.loadmat('elev.mat')
# retrive the actual array. the data set contains also the spatial reference
elev.get('map_data')
data = elev.get('map_data')
# a first simple plot
import pylab
pylab.plot(data)
pylab.show()
# the contour plot
pylab.contour(data)
# obviously data needs to ne reversed
import numpy as np
data_rev = data[::-1]
pylab.contour(data_rev)
# => this is a quick plot. basemap mapping may provide a nicer map!
#######
</source>

== Usage Examples ==

=== Display example ===
Example of Python script, which is processed by {{cmd|g.parser}}:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 by the GRASS Development Team
#
# This program is free software under the GNU General Public
# License (>=v2). Read the file COPYING that comes with GRASS
# for details.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#% keyword: display
#% keyword: raster
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()

</source>

=== Parsing the options and flags ===

{{pyapi|script|script.core|parser}} is an interface to {{cmd|g.parser}}, and allows to parse the ''options'' and ''flags'' passed to your script on the command line. It is to be called at the top-level:

<source lang="python">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

Global variables "options" and "flags" are Python dictionaries containing the options/flags values, keyed by lower-case option/flag names. The values in "options" are strings, those in "flags" are Python booleans. All those variables have to be previously declared in the header of your script.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</source>

'''Passing several floats to a single option:'''

Example:
<source lang="bash">
python my.module.py input=input output=output myoption=0.1,0.2,0.5
</source>

The values in the "options" dictionary returned from the parser()
function are always strings. You can parse the string with:

<source lang="python">
myoption = map(float, options['myoption'].split(','))
</source>

The option definition in the script should have:

<source lang="python">
#% type: double
#% multiple: yes
</source>

This allows g.parser to validate the option syntax, so you can rely
upon the string being in the correct format. If the values have a
fixed range, you can use e.g.:

<source lang="python">
#% options: 0.0-1.0
</source>

to have the parser check that the values fall within the range.

For more information on option definitions, see:

http://grass.osgeo.org/programming7/gislib.html#Complete_Structure_Members_Table

=== Example for embedding r.mapcalc (map algebra) ===

{{pyapi|script|script.raster|mapcalc}} accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

''Best practice'': first copy all of the options[] into separate variables at the beginning of main(), i.e.:

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</source>

Performing multiple computations using <tt>grass.script.raster.mapcalc()</tt>:
<source lang="python">
expr = ";".join([
"$out.r = r#$first * $frac + (1.0 - $frac) * r#$second",
"$out.g = g#$first * $frac + (1.0 - $frac) * g#$second",
"$out.b = b#$first * $frac + (1.0 - $frac) * b#$second"])
grass.mapcalc(expr, out=out, first=first, second=second, frac=percent/100.0)
</source>

Hint: multi-line strings can be separated by using a semicolon instead of a newline.

=== Looping over file names stored in an ASCII file ===

When looping over file names stored in an ASCII file and getting the error

WARNING: Illegal filename <map.f1jan.05216.something
>. Character <
> not allowed.

then the line terminators may be the reason.
When you iterate over a file, the strings include the line terminators (e.g. '\n' or '\r\n'). Use e.g.

<source lang="python">
for line in gl:
renamed = line.rstrip().replace('.','_')
...
</source>

to remove any trailing whitespace (including newlines) from each line.

=== Example for parsing raster category labels ===

How to obtain the text labels
<source lang="python">
# dump cats to file to avoid "too many argument" problem:
p = grass.pipe_command('r.category', map = rastertmp, separator = ';', quiet = True)
cats = []
for line in p.stdout:
cats.append(line.rstrip('\r\n').split(';')[0])
p.wait()

number = len(cats)
if number < 1:
grass.fatal(_("No categories found in raster map"))
</source>

=== Example for parsing category numbers ===

'''Q:''' How to obtain the number of cells of a certain category?

'''A:''' It is recommended to use {{pyapi|script|script.core|pipe_command}} and parse the output, e.g.:

<source lang="python">
p = grass.pipe_command('r.stats',flags='c',input='map')
result = {}
for line in p.stdout:
val,count = line.strip().split()
result[int(val)] = int(count)
p.wait()
</source>

=== Example for getting the region's number of rows and columns ===

'''Q:''' How to obtain the number of rows and columns of the current region?

'''A:''' It is recommended to use the {{pyapi|script|script.core|region}} function which will create a dictionary with values for extents and resolution, e.g.:

<source lang="python">
#!/usr/bin/env python
#-*- coding:utf-8 -*-
#
############################################################################
#
# MODULE: g.region.resolution
# AUTHOR(S): based on a post at GRASS-USER mailing list [1]
# PURPOSE: Parses "g.region -g", prints out number of rows, cols
# COPYLEFT: ;-)
# COMMENT: ...a lot of comments to be easy-to-read for/by beginners
#
#############################################################################
#
#%Module
#% description: Print number of rows, cols of current geographic region
#% keyword: region
#%end

# importing required modules
import sys # the sys module [2]
from grass.script import core as grass # the core module [3]

# information about imported modules can be obtained using the dir() function
# e.g.: dir(sys)

# define the "main" function: get number of rows, cols of region
def main():

# #######################################################################
# the following commented code works but is kept only for learning purposes

## assigning the output of the command "g.region -g" in a string called "return_rows_x_cols"
# return_rows_x_cols = grass.read_command('g.region', flags = 'g')

## parsing arguments of interest (rows, cols) in a dictionary named "rows_x_cols"
# rows_x_cols = grass.parse_key_val(return_rows_x_cols)

## selectively print rows, cols from the dictionary "rows_x_cols"
# print 'rows=%d \ncols=%d' % (int(rows_x_cols['rows']), int(rows_x_cols['cols']))

# #######################################################################

# faster/ easier way: use of the "grass.region()" function
gregion = grass.region()
rows = gregion['rows']
cols = gregion['cols']

# print rows, cols properly formated
print 'rows=%d \ncols=%d' % (rows, cols)

# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly
if __name__ == "__main__": # this allows the script to be used as a module in other scripts or as a standalone script
options, flags = grass.parser() #
sys.exit(main()) #

# Links
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [3] http://grass.osgeo.org/grass71/manuals/libpython
</source>

=== Managing mapsets ===

To check if a certain mapset exists in the active location, use {{pyapi|script|script.core|mapsets}}

<source lang="python">
grass.mapsets(False)
</source>

... returns a list of mapsets in the current location.

=== r.mapcalc example ===

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

grass.mapcalc("MASK=if(($cloudResampName < 0.01000),1,null())",
cloudResampName = cloudResampName)
</source>

The first argument to the mapcalc function is a template (see the Python library documentation for [http://docs.python.org/library/string.html string.Template]). Any keyword arguments (other than <tt>quiet</tt>, <tt>verbose</tt> or <tt>overwrite</tt>) specify substitutions.

=== r.mapcalc example: defining a moving window ===

Moving window of 4 cell in every 8 direction and do a boolean comparison. Boolean value (e.g. the result of a comparison) is an integer, with 1 for true, 0 for false.
Then do a r.mapcalc calculation with the moving window.

<source lang="python">

import grass.script as grass

# define a moving window of 4 cell in every 8 direction
#
# map[4,4] map[4,0] map[4,-4]
# map[3,3] map[3,0] map[3,-3]
# map[2,2] map[2,0] map[2,-2]
# map[1,1] map[1,0] map[1,-1]
# map[0,4] map[0,3] map[0,2] map[0,1] x map[0,-1] map[0,-2] map[0,-3] map[0,-4]
# map[-1,1] map[-1,0] map[-1,-1]
# map[-2,2] map[-2,0] map[-2,-2]
# map[-3,3] map[-3,0] map[-3,-3]
# map[-4,4] map[-4,0] map[-4,-4]

# define the offet duplets

offsets = [d
for j in xrange(1,4+1)
for i in [j,-j]
for d in [(i,0),(0,i),(i,i),(i,-i)]]

# >>>offsets
# [(1, 0), (0, 1), (1, 1), (1, -1), (-1, 0), (0, -1), (-1, -1), (-1, 1), (2, 0), (0, 2), (2, 2), (2, -2), (-2, 0), (0, -2), \
# (-2, -2), (-2, 2), (3, 0), (0, 3), (3, 3), (3, -3), (-3, 0), (0, -3), (-3, -3), (-3, 3), (4, 0), (0, 4), (4, 4), (4, -4), \
# (-4, 0), (0, -4), (-4, -4), (-4, 4)]

# define the calculation term

terms = ["(myelevnc[%d,%d] < myelevnc)" % d
for d in offsets]

# >>>terms
# ['(myelevnc[1,0] < myelevnc)', '(myelevnc[0,1] < myelevnc)', '(myelevnc[1,1] < myelevnc)', '(myelevnc[1,-1] < myelevnc)', \
# '(myelevnc[-1,0] < myelevnc)', '(myelevnc[0,-1] < myelevnc)', '(myelevnc[-1,-1] < myelevnc)', '(myelevnc[-1,1] < myelevnc)',\
# '(myelevnc[2,0] < myelevnc)', '(myelevnc[0,2] < myelevnc)', '(myelevnc[2,2] < myelevnc)', '(myelevnc[2,-2] < myelevnc)', \
# '(myelevnc[-2,0] < myelevnc)', '(myelevnc[0,-2] < myelevnc)', '(myelevnc[-2,-2] < myelevnc)', '(myelevnc[-2,2] < myelevnc)', \
# '(myelevnc[3,0] < myelevnc)', '(myelevnc[0,3] < myelevnc)', '(myelevnc[3,3] < myelevnc)', '(myelevnc[3,-3] < myelevnc)', \
# '(myelevnc[-3,0] < myelevnc)', '(myelevnc[0,-3] < myelevnc)', '(myelevnc[-3,-3] < myelevnc)', '(myelevnc[-3,3] < myelevnc)', \
# '(myelevnc[4,0] < myelevnc)', '(myelevnc[0,4] < myelevnc)', '(myelevnc[4,4] < myelevnc)', '(myelevnc[4,-4] < myelevnc)', \
# '(myelevnc[-4,0] < myelevnc)', '(myelevnc[0,-4] < myelevnc)', '(myelevnc[-4,-4] < myelevnc)', '(myelevnc[-4,4] < myelevnc)']

# define the calculation expression

expr = "elevation_percentile4 = (100.0 / 48.0) * (%s)" % " + ".join(terms)

# >>>expr
# elevation_percentile4 = (100.0 / 48.0) * ((myelevnc[1,0] < myelevnc) + (myelevnc[0,1] < myelevnc) + (myelevnc[1,1] < myelevnc) + \
# (myelevnc[1,-1] < myelevnc) + (myelevnc[-1,0] < myelevnc) + (myelevnc[0,-1] < myelevnc) + (myelevnc[-1,-1] < myelevnc) + \
# (myelevnc[-1,1] < myelevnc) + (myelevnc[2,0] < myelevnc) + (myelevnc[0,2] < myelevnc) + (myelevnc[2,2] < myelevnc) + \
# (myelevnc[2,-2] < myelevnc) + (myelevnc[-2,0] < myelevnc) + (myelevnc[0,-2] < myelevnc) + (myelevnc[-2,-2] < myelevnc) + \
# (myelevnc[-2,2] < myelevnc) + (myelevnc[3,0] < myelevnc) + (myelevnc[0,3] < myelevnc) + (myelevnc[3,3] < myelevnc) + \
# (myelevnc[3,-3] < myelevnc) + (myelevnc[-3,0] < myelevnc) + (myelevnc[0,-3] < myelevnc) + (myelevnc[-3,-3] < myelevnc) + \
# (myelevnc[-3,3] < myelevnc) + (myelevnc[4,0] < myelevnc) + (myelevnc[0,4] < myelevnc) + (myelevnc[4,4] < myelevnc) + \
# (myelevnc[4,-4] < myelevnc) + (myelevnc[-4,0] < myelevnc) + (myelevnc[0,-4] < myelevnc) + (myelevnc[-4,-4] < myelevnc)\
# + (myelevnc[-4,4] < myelevnc))

# do the r.mapcalc calculation with the moving window

grass.mapcalc( expr )

</source>

=== Using output from GRASS modules in the script ===

Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.

Example: get the range of a raster map and use it in {{cmd|r.mapcalc}}. Here you can use {{pyapi|script|script.raster|raster_info}}, e.g.:

<source lang="python">
import grass.script as grass

max = grass.raster_info(inmap)['max']
grass.mapcalc("$outmap = $inmap / $max",
inmap = inmap, outmap = outmap, max = max)
</source>

=== Using output from r.what ===

''Q: How does one return attribute values from a call to the 'r.what' module running in a python script?''

A: If you use <tt>grass.script.raster_what()</tt>, it returns a list of dictionaries.

PyGRASS which requires you to add <tt>stdout_=PIPE</tt>, then you can get the output as a string from <tt>module.outputs.stdout</tt>.

Or using directly the C API through python with (North Carolina dataset example):

<source lang="python">
from grass.pygrass.vector import VectorTopo
from grass.pygrass.raster import RasterRow
from grass.pygrass.gis.region import Region

with RasterRow('elevation', mode='r') as rast:
with VectorTopo('hospitals', mode='r') as hospitals:
region = Region()
for hosp in hospitals:
value = rast.get_value(hosp, region)
if value is not None:
print(hosp.cat, value)
</source>

=== Calling a GRASS module in Python ===

Imagine, you wanted to execute this command in Python:
<source lang="bash">
r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77
</source>

All arguments except the first (which is a flag) are keyword arguments, i.e. <tt>arg = val</tt>. For the flag, use <tt>flags = 'g'</tt> (note that "-g" would be the negative of a Python variable named "g"!). So:

<source lang="python">
grass.run_command('r.profile',
input = input_map,
output = output_file,
profile = [12244.256,-295112.597,12128.012,-295293.77]
</source>
or:
<source lang="python">
profile = [(12244.256,-295112.597),(12128.012,-295293.77)]
</source>

i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function <code>run_command()</code> etc accept lists and tuples.

'''What is the proper way to include keyword-arguments tuples?'''

For example, "g.list -f type=rast,vect" translates into:
<source lang="python">
grass.run_command("g.list", flags="f", type="rast,vect")
</source>
or:
<source lang="python">
grass.run_command("g.list", flags="f", type=["rast","vect"])
</source>

The various *_command() functions accept arbitrary keyword arguments. Any keywords which don't have a specific meaning to either the *_command() function or the Popen constructor are treated as arguments to the GRASS module.

'''What is the proper way to use multiple flags?'''

How can I call a module with multiple flags set (e.g., -a and -b) in GRASS-Python?

flags = "ab"

Example:
<source lang="python">
grass.run_command("r.info", flags="eg", map=["elevation"])
</source>

'''Differences between ''run_command()'' and ''read_command()'':'''

* {{pyapi|script|script.core|run_command}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* {{pyapi|script|script.core|read_command}} executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.

'''How to retrieve error messages from ''read_command()'':'''

None of the existing *_command functions redirect stderr. You can do so with e.g.:

<source lang="python">
def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</source>

This behaves like <tt>read_command()</tt> except that it returns a tuple of (stdout, stderr) rather than just stdout.

=== Interface to copying maps (g.copy) ===

Copy a raster map (for vector, replace "rast" with "vect"):

<source lang="python">
grass.run_command('g.copy', rast = (input, output))
</source>

To generalize it, "datatype" is the form of grass data to copy (eg, rast, vect, etc)

<source lang="python">
grass.run_command('g.copy', **{datatype: (input, output)})
</source>

=== Interface to listing maps (g.list) ===

You may use the functions in [http://grass.osgeo.org/programming7/namespacepython_1_1script_1_1core.html python.script.core.mlist_grouped()]:

<source lang="python">
list_grouped('raster')['PERMANENT']
[..., 'lakes', ..., 'slope', ...
</source>

and

<source lang="python">
mlist_grouped('vector', pattern='*roads*')['PERMANENT']
['railroads', 'roadsmajor']
</source>

See also [[Python/pygrass#Sample_PyGRASS_scripts|Sample PyGRASS scripts]] for an alternative solution.

=== i.group with patterns as name for input ===

Imagery groups can be populated like this:

<source lang="python">
from grass.pygrass.gis import Mapset

run_command("i.group", group="mygroup", input=mset.glist("raster", pattern="mypattern_*"))
</source>

=== Percentage output for progress of computation ===

A) Within a Python script, the {{pyapi|script|script.core|percent}} module method wraps the <tt>g.message -p</tt> command.

B) If you call a GRASS command within the Python code, you have to parse the output by setting <tt>GRASS_MESSAGE_FORMAT=gui</tt> in the environment when running the command and read from the command's stderr; e.g.

<source lang="python">
import grass.script as grass
env = os.environ.copy()
env['GRASS_MESSAGE_FORMAT'] = 'gui'
p = grass.start_command(..., stderr = grass.PIPE, env = env)
# read from p.stderr
p.wait()
</source>

If you need to capture both stdout and stderr, you need to use threads, select, or non-blocking I/O to consume data from both streams as it is generated in order to avoid deadlock.

ALTERNATIVE:

Redirect both stdout and stderr to the same pipe (and hope that the normal output doesn't include anything which will be mistaken for progress/error/etc messages):

<source lang="python">
p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)
</source>

=== NULL data management ===

How to analyse if there are only NULL cells in a map:

If a map contains only null cells, its minimum and maximum will be "NULL":

<source lang="bash">
$ r.mapcalc 'foo = null()'
$ r.info -r foo
min=NULL
max=NULL
</source>

Using the Python API, The 'min' and 'max' values in the result of the {{pyapi|script|script.raster|raster_info}} function will be <tt>None</tt>.

=== Counting cells ===

Counting cells is far more expensive than simply determining whether
there are any non-null cells. Counting cells requires reading the
entire map, while the {{cmd|r.info}} approach only needs to read the metadata
files.

If you do need to count cells, {{cmd|r.stats}} is likely to be more efficient than {{cmd|r.univar}}.

A count loop:

<source lang="python">
while grass.raster_info(inmap)['max'] is not None:
...
</source>

=== Display: overlayed map display with labels ===

Example: display a vector map and overlay its labels on top of the map.

If the environment contains the setting GRASS_PNG_READ=TRUE, d.* commands should overlay their output on an existing image (otherwise the first command creates the file map.png but the second command overwrites the file with only the labels). So the following should work:

<source lang="python">
grass.run_command('d.vect', map='my_shape')
env = os.environ.copy()
env['GRASS_PNG_READ'] = 'TRUE'
grass.run_command('d.labels', labels='my_shape_labels', env = env)
</source>

=== Path to GISDBASE ===
In order to a avoid hardcoded paths to GRASS mapset files like the SQLite DB file, you can get the GISDBASE variable from the environment:
<source lang="python">
import grass.script as grass
import os.path

env = grass.gisenv()

gisdbase = env['GISDBASE']
location = env['LOCATION_NAME']
mapset = env['MAPSET']

path = os.path.join(gisdbase, location, mapset, 'sqlite.db')
</source>

=== Creating a new location ===

Use {{pyapi|script|script.core|create_location}} to create a new location.

=== Use Python reserved keyword ===

'''Q:''' ''r.resamp.bspline'' uses 'lambda' as a command line parameter name, but when you try to use it with {{pyapi|script|script.core|run_command}} or {{pyapi|script|script.core|start_command}} you get an error as lambda is a python reserved keyword. How to work around that?

'''A:''' Append an underscore to the name, i.e.:

<source lang="python">
grass.run_command('r.resamp.bspline', lambda_ = ...)
</source>

Note that this follows Python [http://legacy.python.org/dev/peps/pep-0008/#descriptive-naming-styles PEP8] style guide. In GRASS GIS version 6, you have to prepend the underscore.

=== Controlling the PNG display driver ===

Code fragment to control the {{cmd|pngdriver}} in Python:

<source lang="python">
import os
import sys
from grass.script import core as grass
def main():
os.environ['GRASS_PNGFILE'] = filename
os.environ['GRASS_WIDTH'] = str(width)
os.environ['GRASS_HEIGHT'] = str(height)
grass.run_command('d.his', i='elevation_shade', h='elevation')
</source>

=== Sophisticated cleanup procedure ===

Scripts which create several temporary files need a more sophisticated cleanup procedure which deletes all the tmp maps which have been created. This procedure should also work if the script stops (e.g due to an error).

Solution: Define a list of map names which starts out empty and has names appended to it as the names are generated. Code fragment:

<source lang="python">
import atexit, sys
import grass.script as grass

tmp_rast = []

def cleanup():
for rast in tmp_rast:
grass.run_command("g.remove",
rast = rast,
quiet = True)

def main():
...
while ...:
next_rast = ...
tmp_rast.append(next_rast)
...

if __name__ == "__main__":
options, flags = grass.parser()
atexit.register(cleanup)
sys.exit(main())
</source>

=== Using temporary region for computations ===

There are two possible ways how to define temporary region for raster-based computations within your scripts. First method uses environmental variable WIND_OVERRIDE, the second GRASS_REGION, see {{cmd|variables|desc=GRASS variables}} for more info. The key point is to recover the current region when the script is finished or terminated.

* ''First method'' (WIND_OVERRIDE) is implemented as {{pyapi|script|script.core|use_temp_region}}

<source lang=python>
import grass.script as grass

# store the current region settings and installs an atexit
# handler to recover the current region on script termination
grass.use_temp_region()

grass.run_command('g.region', region='detail')

grass.mapcalc('map = 1', overwrite=True)

# after making operations using the temporary region,
# to unset the temporary WIND_OVERRIDE file and remove any
# region named by it, it is possible to use del_temp_region
grass.del_temp_region()
</source>

* ''Second method'' (GRASS_REGION) doesn't store current region settings to any temporary region, it just defines GRASS_REGION which forces GIS Library to use this settings for raster-based computations instead of the settings stored in WIND file (ie. current region). See {{pyapi|script|script.core|region_env}}.

<source lang=python>
import os
import grass.script as grass

# copy environment and define GRASS_REGION environmental variable
# same as `g.region region=detail`
env = os.environ.copy()
env['GRASS_REGION'] = grass.region_env(region='detail')

grass.mapcalc('map = 1', overwrite=True, env=env)
</source>

== Direct Access from wxGUI ==

[[wxGUI]] Layer Manager in GRASS GIS comes with "Python shell" which enables users to type and execute python commands directly in wxGUI environment.

[[Image:wxgui-pyshell.png|center|400px|Embedded interactive Python Shell in wxGUI Layer Manager]]

== See also ==

* [[GRASS GIS Jupyter notebooks]]
* [[Working with GRASS without starting it explicitly‎]]
* Many more tutorials under [[:Category:Python]]

GRASS Python Scripting Library

2018-02-09T12:44:52Z

⚠️BernardoBrenoPacas: Included grass.del_temp_region() to delete the temporary region file

{{Python}}
Python API documentation:

* [http://grass.osgeo.org/grass70/manuals/libpython/ Python API for GRASS GIS 7] and [http://grass.osgeo.org/grass70/manuals/libpython/script_intro.html Python Scripting Library]
* [http://grass.osgeo.org/programming6/pythonlib.html for GRASS GIS 6]: core.py, db.py, raster.py, vector.py, setup.py, array.py task.py

The GRASS Python Scripting Library can be imported by statement

<source lang=python>
import grass.script as gscript
</source>

The other packages such as PyGRASS can be imported in a similar way.

The code in {{src|lib/python/|lib/python}} provides <tt>grass.script</tt> and other packages in order to support GRASS scripts written in Python. The {{src|scripts}} directory of GRASS GIS 7 contains a series of examples actually provided to the end users (while the script in GRASS GIS 6 are shell scripts).

For more general info, see also [[GRASS and Python]] and see also [[Converting Bash scripts to Python]] if you have some Bash scripts you want to rewrite to Python.

== Uses for read, feed and pipe, start and exec commands ==

All of the <tt>*_command</tt> functions use {{pyapi|script|script.core|make_command}} to construct a command
line for a program which uses the {{cmd|g.parser|desc=GRASS parser}}. Most of them then pass
that command line to <tt>subprocess.Popen()</tt> via {{pyapi|script|script.core|start_command}}, except
for {{pyapi|script|script.core|exec_command}} which uses <tt>os.execvpe()</tt>.

[To be precise, they use <tt>grass.Popen()</tt>, which just calls
<tt>subprocess.Popen()</tt> with 'shell=True' on Windows and 'shell=False'
otherwise. On Windows, you need to use 'shell=True' to be able to
execute scripts (including batch files); 'shell=False' only works with
binary executables.]

{{pyapi|script|script.core|start_command}} separates the arguments into those which
<tt>subprocess.Popen()</tt> understands and the rest. The rest are passed to
<tt>make_command()</tt> to construct a command line which is passed as the
"args" parameter to <tt>subprocess.Popen()</tt>.

In other words, {{pyapi|script|script.core|start_command}} is a GRASS-oriented interface to
<tt>subprocess.Popen()</tt>. It should be suitable for any situation where you
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is {{cmd|r.mapcalc}} in 6.x).

Most of the others are convenience wrappers around <tt>start_command()</tt>, for common use cases.

* {{pyapi|script|script.core|run_command}} calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to <tt>system()</tt>.

* {{pyapi|script|script.core|pipe_command}} calls <tt>start_command()</tt> with 'stdout=PIPE' and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").

* {{pyapi|script|script.core|feed_command}} calls <tt>start_command()</tt> with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")

* {{pyapi|script|script.core|read_command}} calls <tt>pipe_command()</tt>, reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.

* {{pyapi|script|script.core|write_command}} calls <tt>feed_command()</tt>, sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".

* {{pyapi|script|script.core|parse_command}} calls <tt>read_command()</tt> and parses its output as key-value pairs. Useful for obtaining information from {{cmd|g.region}}, {{cmd|g.proj}}, {{cmd|r.info}}, etc.

* {{pyapi|script|script.core|exec_command}} doesn't use <tt>start_command()</tt> but <tt>os.execvpe()</tt>. This causes the specified command to replace the current program (i.e. the Python script), so <tt>exec_command()</tt> never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step. Notes: exec_command() is rarely appropriate. You probably want run_command() instead. On Windows, exec_command() will probably require the ".exe" suffix.

If you have any other questions, you might want to look at the code ({{src|lib/python/core.py}}). Most of these functions are only a few lines long.

=== Hints for parse_command() ===

To turn this command
g.rename rast=old_name,new_name
into a g.parse_command() call, you need to consider that it is a function call with three arguments:
# "g.rename"
# rast=old_name
# new_name

The second argument is a keyword argument, the first and third are
positional (non-keyword) arguments. Python doesn't allow positional
arguments to follow keyword arguments; positional arguments come
first, keyword arguments last.

Given the context, it's safe to assume that you want to pass a pair of
map names as the value to the rast= option. This requires explicit
parentheses so that the comma is treated as forming a tuple rather
than as an argument separator:

g.parse_command("g.rename", rast=(old_name,new_name))

The parentheses in a tuple value can only be omitted if it doesn't
result in the comma being ambiguous (as is the case in a function
call).

== Interfacing ==

=== Interfacing with NumPy ===

The {{pyapi|script|script.array|array}} module defines a <code>class array</code> which is a subclass of [http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html numpy.memmap] with <code>.read()</code> and <code>.write()</code> methods to read/write the underlying file via {{cmd|r.out.bin}}/{{cmd|r.in.bin}}. Metadata can be read with {{pyapi|script|script.raster|raster_info}}:

Example:

<source lang="python">
import grass.script as grass
import grass.script.array as garray

def main():
map = "elevation.dem"

# read map
a = garray.array()
a.read(map)

# get raster map info
print grass.raster_info(map)['datatype']
i = grass.raster_info(map)

# get computational region info
c = grass.region()
print "rows: %d" % c['rows']
print "cols: %d" % c['cols']

# new array for result
b = garray.array()
# calculate new map from input map and store as GRASS raster map
b[...] = (a / 50).astype(int) * 50
b.write("elev.50m")
</source>

The size of the array is taken from the current region ([[computational region]]).

The main drawback of using numpy is that you're limited by available
memory. Using a subclass of <code>numpy.memmap</code> lets you use files which may
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.

'''NULL (no data) management:'''

For integer maps, the NULL value is -2^31 = -2147483648. For floating-point maps, the NULL value is NaN. Note that the null= parameter for read() and write() specifies the value in the numpy array which is mapped to/from null values in the GRASS raster map.

If you're using floating-point numpy arrays, then use (Note: This assumes that atof() and sscanf("%lf") recognise "nan"; this is the case on Linux, but doesn't appear to work on Windows)
null=numpy.nan

For integer arrays, using
null=-2147483648
will ensure that valid values don't collide with NYLLs.

'''MASK support:'''

The function grass.script.array.read() and ...write() use r.out.bin and r.in.bin respectively. r.out.bin respects the MASK.

=== Interfacing with NumPy and SciPy ===

[http://docs.scipy.org/doc/scipy/reference/index.html SciPy] offers simple access to complex calculations. Example:

<source lang="python">
from scipy import stats
import grass.script as grass
import grass.script.array as garray

def main():
map = "elevation.dem"

x = garray.array()
x.read(map)

# Descriptive Statistics:
print "max, min, mean, var:"
print x.max(), x.min(), x.mean(), x.var()
print "Skewness test: z-score and 2-sided p-value:"
print stats.skewtest(stats.skew(x))
</source>

=== Interfacing with NumPy, SciPy and Matlab ===

One may also use the SciPy - Matlab interface:

r.out.mat input=elevation output=elev.mat

<source lang="python">
### PY ###
import scipy.io as sio
# load data
elev = sio.loadmat('elev.mat')
# retrive the actual array. the data set contains also the spatial reference
elev.get('map_data')
data = elev.get('map_data')
# a first simple plot
import pylab
pylab.plot(data)
pylab.show()
# the contour plot
pylab.contour(data)
# obviously data needs to ne reversed
import numpy as np
data_rev = data[::-1]
pylab.contour(data_rev)
# => this is a quick plot. basemap mapping may provide a nicer map!
#######
</source>

== Usage Examples ==

=== Display example ===
Example of Python script, which is processed by {{cmd|g.parser}}:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 by the GRASS Development Team
#
# This program is free software under the GNU General Public
# License (>=v2). Read the file COPYING that comes with GRASS
# for details.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#% keyword: display
#% keyword: raster
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()

</source>

=== Parsing the options and flags ===

{{pyapi|script|script.core|parser}} is an interface to {{cmd|g.parser}}, and allows to parse the ''options'' and ''flags'' passed to your script on the command line. It is to be called at the top-level:

<source lang="python">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

Global variables "options" and "flags" are Python dictionaries containing the options/flags values, keyed by lower-case option/flag names. The values in "options" are strings, those in "flags" are Python booleans. All those variables have to be previously declared in the header of your script.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</source>

'''Passing several floats to a single option:'''

Example:
<source lang="bash">
python my.module.py input=input output=output myoption=0.1,0.2,0.5
</source>

The values in the "options" dictionary returned from the parser()
function are always strings. You can parse the string with:

<source lang="python">
myoption = map(float, options['myoption'].split(','))
</source>

The option definition in the script should have:

<source lang="python">
#% type: double
#% multiple: yes
</source>

This allows g.parser to validate the option syntax, so you can rely
upon the string being in the correct format. If the values have a
fixed range, you can use e.g.:

<source lang="python">
#% options: 0.0-1.0
</source>

to have the parser check that the values fall within the range.

For more information on option definitions, see:

http://grass.osgeo.org/programming7/gislib.html#Complete_Structure_Members_Table

=== Example for embedding r.mapcalc (map algebra) ===

{{pyapi|script|script.raster|mapcalc}} accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

''Best practice'': first copy all of the options[] into separate variables at the beginning of main(), i.e.:

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</source>

Performing multiple computations using <tt>grass.script.raster.mapcalc()</tt>:
<source lang="python">
expr = ";".join([
"$out.r = r#$first * $frac + (1.0 - $frac) * r#$second",
"$out.g = g#$first * $frac + (1.0 - $frac) * g#$second",
"$out.b = b#$first * $frac + (1.0 - $frac) * b#$second"])
grass.mapcalc(expr, out=out, first=first, second=second, frac=percent/100.0)
</source>

Hint: multi-line strings can be separated by using a semicolon instead of a newline.

=== Looping over file names stored in an ASCII file ===

When looping over file names stored in an ASCII file and getting the error

WARNING: Illegal filename <map.f1jan.05216.something
>. Character <
> not allowed.

then the line terminators may be the reason.
When you iterate over a file, the strings include the line terminators (e.g. '\n' or '\r\n'). Use e.g.

<source lang="python">
for line in gl:
renamed = line.rstrip().replace('.','_')
...
</source>

to remove any trailing whitespace (including newlines) from each line.

=== Example for parsing raster category labels ===

How to obtain the text labels
<source lang="python">
# dump cats to file to avoid "too many argument" problem:
p = grass.pipe_command('r.category', map = rastertmp, separator = ';', quiet = True)
cats = []
for line in p.stdout:
cats.append(line.rstrip('\r\n').split(';')[0])
p.wait()

number = len(cats)
if number < 1:
grass.fatal(_("No categories found in raster map"))
</source>

=== Example for parsing category numbers ===

'''Q:''' How to obtain the number of cells of a certain category?

'''A:''' It is recommended to use {{pyapi|script|script.core|pipe_command}} and parse the output, e.g.:

<source lang="python">
p = grass.pipe_command('r.stats',flags='c',input='map')
result = {}
for line in p.stdout:
val,count = line.strip().split()
result[int(val)] = int(count)
p.wait()
</source>

=== Example for getting the region's number of rows and columns ===

'''Q:''' How to obtain the number of rows and columns of the current region?

'''A:''' It is recommended to use the {{pyapi|script|script.core|region}} function which will create a dictionary with values for extents and resolution, e.g.:

<source lang="python">
#!/usr/bin/env python
#-*- coding:utf-8 -*-
#
############################################################################
#
# MODULE: g.region.resolution
# AUTHOR(S): based on a post at GRASS-USER mailing list [1]
# PURPOSE: Parses "g.region -g", prints out number of rows, cols
# COPYLEFT: ;-)
# COMMENT: ...a lot of comments to be easy-to-read for/by beginners
#
#############################################################################
#
#%Module
#% description: Print number of rows, cols of current geographic region
#% keyword: region
#%end

# importing required modules
import sys # the sys module [2]
from grass.script import core as grass # the core module [3]

# information about imported modules can be obtained using the dir() function
# e.g.: dir(sys)

# define the "main" function: get number of rows, cols of region
def main():

# #######################################################################
# the following commented code works but is kept only for learning purposes

## assigning the output of the command "g.region -g" in a string called "return_rows_x_cols"
# return_rows_x_cols = grass.read_command('g.region', flags = 'g')

## parsing arguments of interest (rows, cols) in a dictionary named "rows_x_cols"
# rows_x_cols = grass.parse_key_val(return_rows_x_cols)

## selectively print rows, cols from the dictionary "rows_x_cols"
# print 'rows=%d \ncols=%d' % (int(rows_x_cols['rows']), int(rows_x_cols['cols']))

# #######################################################################

# faster/ easier way: use of the "grass.region()" function
gregion = grass.region()
rows = gregion['rows']
cols = gregion['cols']

# print rows, cols properly formated
print 'rows=%d \ncols=%d' % (rows, cols)

# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly
if __name__ == "__main__": # this allows the script to be used as a module in other scripts or as a standalone script
options, flags = grass.parser() #
sys.exit(main()) #

# Links
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [3] http://grass.osgeo.org/grass71/manuals/libpython
</source>

=== Managing mapsets ===

To check if a certain mapset exists in the active location, use {{pyapi|script|script.core|mapsets}}

<source lang="python">
grass.mapsets(False)
</source>

... returns a list of mapsets in the current location.

=== r.mapcalc example ===

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

grass.mapcalc("MASK=if(($cloudResampName < 0.01000),1,null())",
cloudResampName = cloudResampName)
</source>

The first argument to the mapcalc function is a template (see the Python library documentation for [http://docs.python.org/library/string.html string.Template]). Any keyword arguments (other than <tt>quiet</tt>, <tt>verbose</tt> or <tt>overwrite</tt>) specify substitutions.

=== r.mapcalc example: defining a moving window ===

Moving window of 4 cell in every 8 direction and do a boolean comparison. Boolean value (e.g. the result of a comparison) is an integer, with 1 for true, 0 for false.
Then do a r.mapcalc calculation with the moving window.

<source lang="python">

import grass.script as grass

# define a moving window of 4 cell in every 8 direction
#
# map[4,4] map[4,0] map[4,-4]
# map[3,3] map[3,0] map[3,-3]
# map[2,2] map[2,0] map[2,-2]
# map[1,1] map[1,0] map[1,-1]
# map[0,4] map[0,3] map[0,2] map[0,1] x map[0,-1] map[0,-2] map[0,-3] map[0,-4]
# map[-1,1] map[-1,0] map[-1,-1]
# map[-2,2] map[-2,0] map[-2,-2]
# map[-3,3] map[-3,0] map[-3,-3]
# map[-4,4] map[-4,0] map[-4,-4]

# define the offet duplets

offsets = [d
for j in xrange(1,4+1)
for i in [j,-j]
for d in [(i,0),(0,i),(i,i),(i,-i)]]

# >>>offsets
# [(1, 0), (0, 1), (1, 1), (1, -1), (-1, 0), (0, -1), (-1, -1), (-1, 1), (2, 0), (0, 2), (2, 2), (2, -2), (-2, 0), (0, -2), \
# (-2, -2), (-2, 2), (3, 0), (0, 3), (3, 3), (3, -3), (-3, 0), (0, -3), (-3, -3), (-3, 3), (4, 0), (0, 4), (4, 4), (4, -4), \
# (-4, 0), (0, -4), (-4, -4), (-4, 4)]

# define the calculation term

terms = ["(myelevnc[%d,%d] < myelevnc)" % d
for d in offsets]

# >>>terms
# ['(myelevnc[1,0] < myelevnc)', '(myelevnc[0,1] < myelevnc)', '(myelevnc[1,1] < myelevnc)', '(myelevnc[1,-1] < myelevnc)', \
# '(myelevnc[-1,0] < myelevnc)', '(myelevnc[0,-1] < myelevnc)', '(myelevnc[-1,-1] < myelevnc)', '(myelevnc[-1,1] < myelevnc)',\
# '(myelevnc[2,0] < myelevnc)', '(myelevnc[0,2] < myelevnc)', '(myelevnc[2,2] < myelevnc)', '(myelevnc[2,-2] < myelevnc)', \
# '(myelevnc[-2,0] < myelevnc)', '(myelevnc[0,-2] < myelevnc)', '(myelevnc[-2,-2] < myelevnc)', '(myelevnc[-2,2] < myelevnc)', \
# '(myelevnc[3,0] < myelevnc)', '(myelevnc[0,3] < myelevnc)', '(myelevnc[3,3] < myelevnc)', '(myelevnc[3,-3] < myelevnc)', \
# '(myelevnc[-3,0] < myelevnc)', '(myelevnc[0,-3] < myelevnc)', '(myelevnc[-3,-3] < myelevnc)', '(myelevnc[-3,3] < myelevnc)', \
# '(myelevnc[4,0] < myelevnc)', '(myelevnc[0,4] < myelevnc)', '(myelevnc[4,4] < myelevnc)', '(myelevnc[4,-4] < myelevnc)', \
# '(myelevnc[-4,0] < myelevnc)', '(myelevnc[0,-4] < myelevnc)', '(myelevnc[-4,-4] < myelevnc)', '(myelevnc[-4,4] < myelevnc)']

# define the calculation expression

expr = "elevation_percentile4 = (100.0 / 48.0) * (%s)" % " + ".join(terms)

# >>>expr
# elevation_percentile4 = (100.0 / 48.0) * ((myelevnc[1,0] < myelevnc) + (myelevnc[0,1] < myelevnc) + (myelevnc[1,1] < myelevnc) + \
# (myelevnc[1,-1] < myelevnc) + (myelevnc[-1,0] < myelevnc) + (myelevnc[0,-1] < myelevnc) + (myelevnc[-1,-1] < myelevnc) + \
# (myelevnc[-1,1] < myelevnc) + (myelevnc[2,0] < myelevnc) + (myelevnc[0,2] < myelevnc) + (myelevnc[2,2] < myelevnc) + \
# (myelevnc[2,-2] < myelevnc) + (myelevnc[-2,0] < myelevnc) + (myelevnc[0,-2] < myelevnc) + (myelevnc[-2,-2] < myelevnc) + \
# (myelevnc[-2,2] < myelevnc) + (myelevnc[3,0] < myelevnc) + (myelevnc[0,3] < myelevnc) + (myelevnc[3,3] < myelevnc) + \
# (myelevnc[3,-3] < myelevnc) + (myelevnc[-3,0] < myelevnc) + (myelevnc[0,-3] < myelevnc) + (myelevnc[-3,-3] < myelevnc) + \
# (myelevnc[-3,3] < myelevnc) + (myelevnc[4,0] < myelevnc) + (myelevnc[0,4] < myelevnc) + (myelevnc[4,4] < myelevnc) + \
# (myelevnc[4,-4] < myelevnc) + (myelevnc[-4,0] < myelevnc) + (myelevnc[0,-4] < myelevnc) + (myelevnc[-4,-4] < myelevnc)\
# + (myelevnc[-4,4] < myelevnc))

# do the r.mapcalc calculation with the moving window

grass.mapcalc( expr )

</source>

=== Using output from GRASS modules in the script ===

Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.

Example: get the range of a raster map and use it in {{cmd|r.mapcalc}}. Here you can use {{pyapi|script|script.raster|raster_info}}, e.g.:

<source lang="python">
import grass.script as grass

max = grass.raster_info(inmap)['max']
grass.mapcalc("$outmap = $inmap / $max",
inmap = inmap, outmap = outmap, max = max)
</source>

=== Using output from r.what ===

''Q: How does one return attribute values from a call to the 'r.what' module running in a python script?''

A: If you use <tt>grass.script.raster_what()</tt>, it returns a list of dictionaries.

PyGRASS which requires you to add <tt>stdout_=PIPE</tt>, then you can get the output as a string from <tt>module.outputs.stdout</tt>.

Or using directly the C API through python with (North Carolina dataset example):

<source lang="python">
from grass.pygrass.vector import VectorTopo
from grass.pygrass.raster import RasterRow
from grass.pygrass.gis.region import Region

with RasterRow('elevation', mode='r') as rast:
with VectorTopo('hospitals', mode='r') as hospitals:
region = Region()
for hosp in hospitals:
value = rast.get_value(hosp, region)
if value is not None:
print(hosp.cat, value)
</source>

=== Calling a GRASS module in Python ===

Imagine, you wanted to execute this command in Python:
<source lang="bash">
r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77
</source>

All arguments except the first (which is a flag) are keyword arguments, i.e. <tt>arg = val</tt>. For the flag, use <tt>flags = 'g'</tt> (note that "-g" would be the negative of a Python variable named "g"!). So:

<source lang="python">
grass.run_command('r.profile',
input = input_map,
output = output_file,
profile = [12244.256,-295112.597,12128.012,-295293.77]
</source>
or:
<source lang="python">
profile = [(12244.256,-295112.597),(12128.012,-295293.77)]
</source>

i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function <code>run_command()</code> etc accept lists and tuples.

'''What is the proper way to include keyword-arguments tuples?'''

For example, "g.list -f type=rast,vect" translates into:
<source lang="python">
grass.run_command("g.list", flags="f", type="rast,vect")
</source>
or:
<source lang="python">
grass.run_command("g.list", flags="f", type=["rast","vect"])
</source>

The various *_command() functions accept arbitrary keyword arguments. Any keywords which don't have a specific meaning to either the *_command() function or the Popen constructor are treated as arguments to the GRASS module.

'''What is the proper way to use multiple flags?'''

How can I call a module with multiple flags set (e.g., -a and -b) in GRASS-Python?

flags = "ab"

Example:
<source lang="python">
grass.run_command("r.info", flags="eg", map=["elevation"])
</source>

'''Differences between ''run_command()'' and ''read_command()'':'''

* {{pyapi|script|script.core|run_command}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* {{pyapi|script|script.core|read_command}} executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.

'''How to retrieve error messages from ''read_command()'':'''

None of the existing *_command functions redirect stderr. You can do so with e.g.:

<source lang="python">
def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</source>

This behaves like <tt>read_command()</tt> except that it returns a tuple of (stdout, stderr) rather than just stdout.

=== Interface to copying maps (g.copy) ===

Copy a raster map (for vector, replace "rast" with "vect"):

<source lang="python">
grass.run_command('g.copy', rast = (input, output))
</source>

To generalize it, "datatype" is the form of grass data to copy (eg, rast, vect, etc)

<source lang="python">
grass.run_command('g.copy', **{datatype: (input, output)})
</source>

=== Interface to listing maps (g.list) ===

You may use the functions in [http://grass.osgeo.org/programming7/namespacepython_1_1script_1_1core.html python.script.core.mlist_grouped()]:

<source lang="python">
list_grouped('raster')['PERMANENT']
[..., 'lakes', ..., 'slope', ...
</source>

and

<source lang="python">
mlist_grouped('vector', pattern='*roads*')['PERMANENT']
['railroads', 'roadsmajor']
</source>

See also [[Python/pygrass#Sample_PyGRASS_scripts|Sample PyGRASS scripts]] for an alternative solution.

=== i.group with patterns as name for input ===

Imagery groups can be populated like this:

<source lang="python">
from grass.pygrass.gis import Mapset

run_command("i.group", group="mygroup", input=mset.glist("raster", pattern="mypattern_*"))
</source>

=== Percentage output for progress of computation ===

A) Within a Python script, the {{pyapi|script|script.core|percent}} module method wraps the <tt>g.message -p</tt> command.

B) If you call a GRASS command within the Python code, you have to parse the output by setting <tt>GRASS_MESSAGE_FORMAT=gui</tt> in the environment when running the command and read from the command's stderr; e.g.

<source lang="python">
import grass.script as grass
env = os.environ.copy()
env['GRASS_MESSAGE_FORMAT'] = 'gui'
p = grass.start_command(..., stderr = grass.PIPE, env = env)
# read from p.stderr
p.wait()
</source>

If you need to capture both stdout and stderr, you need to use threads, select, or non-blocking I/O to consume data from both streams as it is generated in order to avoid deadlock.

ALTERNATIVE:

Redirect both stdout and stderr to the same pipe (and hope that the normal output doesn't include anything which will be mistaken for progress/error/etc messages):

<source lang="python">
p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)
</source>

=== NULL data management ===

How to analyse if there are only NULL cells in a map:

If a map contains only null cells, its minimum and maximum will be "NULL":

<source lang="bash">
$ r.mapcalc 'foo = null()'
$ r.info -r foo
min=NULL
max=NULL
</source>

Using the Python API, The 'min' and 'max' values in the result of the {{pyapi|script|script.raster|raster_info}} function will be <tt>None</tt>.

=== Counting cells ===

Counting cells is far more expensive than simply determining whether
there are any non-null cells. Counting cells requires reading the
entire map, while the {{cmd|r.info}} approach only needs to read the metadata
files.

If you do need to count cells, {{cmd|r.stats}} is likely to be more efficient than {{cmd|r.univar}}.

A count loop:

<source lang="python">
while grass.raster_info(inmap)['max'] is not None:
...
</source>

=== Display: overlayed map display with labels ===

Example: display a vector map and overlay its labels on top of the map.

If the environment contains the setting GRASS_PNG_READ=TRUE, d.* commands should overlay their output on an existing image (otherwise the first command creates the file map.png but the second command overwrites the file with only the labels). So the following should work:

<source lang="python">
grass.run_command('d.vect', map='my_shape')
env = os.environ.copy()
env['GRASS_PNG_READ'] = 'TRUE'
grass.run_command('d.labels', labels='my_shape_labels', env = env)
</source>

=== Path to GISDBASE ===
In order to a avoid hardcoded paths to GRASS mapset files like the SQLite DB file, you can get the GISDBASE variable from the environment:
<source lang="python">
import grass.script as grass
import os.path

env = grass.gisenv()

gisdbase = env['GISDBASE']
location = env['LOCATION_NAME']
mapset = env['MAPSET']

path = os.path.join(gisdbase, location, mapset, 'sqlite.db')
</source>

=== Creating a new location ===

Use {{pyapi|script|script.core|create_location}} to create a new location.

=== Use Python reserved keyword ===

'''Q:''' ''r.resamp.bspline'' uses 'lambda' as a command line parameter name, but when you try to use it with {{pyapi|script|script.core|run_command}} or {{pyapi|script|script.core|start_command}} you get an error as lambda is a python reserved keyword. How to work around that?

'''A:''' Append an underscore to the name, i.e.:

<source lang="python">
grass.run_command('r.resamp.bspline', lambda_ = ...)
</source>

Note that this follows Python [http://legacy.python.org/dev/peps/pep-0008/#descriptive-naming-styles PEP8] style guide. In GRASS GIS version 6, you have to prepend the underscore.

=== Controlling the PNG display driver ===

Code fragment to control the {{cmd|pngdriver}} in Python:

<source lang="python">
import os
import sys
from grass.script import core as grass
def main():
os.environ['GRASS_PNGFILE'] = filename
os.environ['GRASS_WIDTH'] = str(width)
os.environ['GRASS_HEIGHT'] = str(height)
grass.run_command('d.his', i='elevation_shade', h='elevation')
</source>

=== Sophisticated cleanup procedure ===

Scripts which create several temporary files need a more sophisticated cleanup procedure which deletes all the tmp maps which have been created. This procedure should also work if the script stops (e.g due to an error).

Solution: Define a list of map names which starts out empty and has names appended to it as the names are generated. Code fragment:

<source lang="python">
import atexit, sys
import grass.script as grass

tmp_rast = []

def cleanup():
for rast in tmp_rast:
grass.run_command("g.remove",
rast = rast,
quiet = True)

def main():
...
while ...:
next_rast = ...
tmp_rast.append(next_rast)
...

if __name__ == "__main__":
options, flags = grass.parser()
atexit.register(cleanup)
sys.exit(main())
</source>

=== Using temporary region for computations ===

There are two possible ways how to define temporary region for raster-based computations within your scripts. First method uses environmental variable WIND_OVERRIDE, the second GRASS_REGION, see {{cmd|variables|desc=GRASS variables}} for more info. The key point is to recover the current region when the script is finished or terminated.

* ''First method'' (WIND_OVERRIDE) is implemented as {{pyapi|script|script.core|use_temp_region}}

<source lang=python>
import grass.script as grass

# store the current region settings and installs an atexit
# handler to recover the current region on script termination
grass.use_temp_region()

grass.run_command('g.region', region='detail')

grass.mapcalc('map = 1', overwrite=True)

# to unset the temporary WIND_OVERRIDE file and remove any
# region named by it, use:
grass.del_temp_region():
</source>

* ''Second method'' (GRASS_REGION) doesn't store current region settings to any temporary region, it just defines GRASS_REGION which forces GIS Library to use this settings for raster-based computations instead of the settings stored in WIND file (ie. current region). See {{pyapi|script|script.core|region_env}}.

<source lang=python>
import os
import grass.script as grass

# copy environment and define GRASS_REGION environmental variable
# same as `g.region region=detail`
env = os.environ.copy()
env['GRASS_REGION'] = grass.region_env(region='detail')

grass.mapcalc('map = 1', overwrite=True, env=env)
</source>

== Direct Access from wxGUI ==

[[wxGUI]] Layer Manager in GRASS GIS comes with "Python shell" which enables users to type and execute python commands directly in wxGUI environment.

[[Image:wxgui-pyshell.png|center|400px|Embedded interactive Python Shell in wxGUI Layer Manager]]

== See also ==

* [[GRASS GIS Jupyter notebooks]]
* [[Working with GRASS without starting it explicitly‎]]
* Many more tutorials under [[:Category:Python]]