GRASS Python Scripting Library

Python API documentation:

• Python API for GRASS GIS 7 and Python Scripting Library
• 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

import grass.script as gscript

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

The code in lib/python/ provides grass.script and other packages in order to support GRASS scripts written in Python. The 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 *_command functions use script.core.make_command() to construct a command line for a program which uses the GRASS parser. Most of them then pass that command line to subprocess.Popen() via script.core.start_command(), except for script.core.exec_command() which uses os.execvpe().

[To be precise, they use grass.Popen(), which just calls subprocess.Popen() 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.]

script.core.start_command() separates the arguments into those which subprocess.Popen() understands and the rest. The rest are passed to make_command() to construct a command line which is passed as the "args" parameter to subprocess.Popen().

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

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

• 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 system().

• script.core.pipe_command() calls start_command() 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").

• script.core.feed_command() calls start_command() 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")

• script.core.read_command() calls pipe_command(), reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.

• script.core.write_command() calls feed_command(), 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".

• script.core.parse_command() calls read_command() and parses its output as key-value pairs. Useful for obtaining information from g.region, g.proj, r.info, etc.

• script.core.exec_command() doesn't use start_command() but os.execvpe(). This causes the specified command to replace the current program (i.e. the Python script), so exec_command() 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 (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:

1. "g.rename"
2. rast=old_name
3. 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 script.array.array() module defines a class array which is a subclass of numpy.memmap with .read() and .write() methods to read/write the underlying file via r.out.bin/r.in.bin. Metadata can be read with script.raster.raster_info():

Example:

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")

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 numpy.memmap 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

SciPy offers simple access to complex calculations. Example:

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))

Interfacing with NumPy, SciPy and Matlab

One may also use the SciPy - Matlab interface:

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

    ### 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!
    #######

Usage Examples

Display example

Example of Python script, which is processed by g.parser:

#!/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()

Parsing the options and flags

script.core.parser() is an interface to 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:

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

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.

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

Passing several floats to a single option:

Example:

python my.module.py input=input output=output myoption=0.1,0.2,0.5

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

        myoption = map(float, options['myoption'].split(','))

The option definition in the script should have:

        #% type: double
        #% multiple: yes

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.:

        #% options: 0.0-1.0

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)

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

grass.mapcalc("${out} = ${rast1} + ${rast2}",
              out = options['output'],
              rast1 = options['raster1'],
              rast2 = options['raster2'])

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

def main():
    output = options['output']
    raster1 = options['raster1']
    raster2 = options['raster2']
 
    ...
 
    grass.mapcalc("${out} = ${rast1} + ${rast2}",
                  out = output,
                  rast1 = raster1,
                  rast2 = raster2)

Performing multiple computations using grass.script.raster.mapcalc():

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)

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.

    for line in gl:
        renamed = line.rstrip().replace('.','_')
        ...

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

Example for parsing raster category labels

How to obtain the text labels

    # 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"))

Example for parsing category numbers

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

A: It is recommended to use script.core.pipe_command() and parse the output, e.g.:

       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()

Example for parsing the region output of a module

Some of the GRASS GIS modules are delivering region information (e.g. r.in.xyz which scans a LiDAR file for the extent of the point cloud). The retrieved region settings (using -g flag for script style output) can be parsed in Python:

import os
from grass.script import core as gcore

from grass.pygrass.modules.shortcuts import general as g
from grass.pygrass.modules.shortcuts import raster as r

# scan a LiDAR xyz point file for its extent
compregion = gcore.parse_command("r.in.xyz", input="tmp.xyz", separator="space", flags="sg", output="bbox",
                                  parse=(gcore.parse_key_val, {'sep': '=', 'vsep': ' '}))
print(compregion)
# set computational region from LiDAR extent
# hint: we turn here the dictionary to a region by unpacking the dictionary:
g.region(res="1", flags="p", **compregion)

Note the two * above which unpack the dictionary (see also the related Python manual page).

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 script.core.region() function which will create a dictionary with values for extents and resolution, e.g.:

#!/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 formatted 
    print 'rows=%d \ncols=%d' % (rows, cols)

    # average resolution (in case of non-square pixels)
    avg_res=(gregion['nsres'] + gregion['ewres']) / 2.0

# 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] https://grass.osgeo.org/grass75/manuals/libpython

Managing mapsets

To check if a certain mapset exists in the active location, use script.core.mapsets()

       grass.mapsets(False)

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

r.mapcalc example

Example of Python script, which is processed by g.parser:

The shell script line:

  r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"

would be written like this:

       import grass.script as grass

       ...

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

The first argument to the mapcalc function is a template (see the Python library documentation for string.Template). Any keyword arguments (other than quiet, verbose or overwrite) 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.

       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 )

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 r.mapcalc. Here you can use script.raster.raster_info(), e.g.:

       import grass.script as grass

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

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 grass.script.raster_what(), it returns a list of dictionaries.

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

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

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)

Avoiding a syntax error for r.rescale

Q: How to avoid a syntax error for r.rescale related to "from=" ?

A: "from" is a reserved word, use from_ instead:

grass.run_command('r.rescale', input=mis1, output=mis1_8bit, from_='0,2048', to='0,255')

Calling a GRASS module in Python

Imagine, you wanted to execute this command in Python:

  r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77

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

       grass.run_command('r.profile',
               input = input_map,
               output = output_file,
               profile = [12244.256,-295112.597,12128.012,-295293.77]

or:

               profile = [(12244.256,-295112.597),(12128.012,-295293.77)]

i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function run_command() 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:

       grass.run_command("g.list", flags="f", type="rast,vect")

or:

       grass.run_command("g.list", flags="f", type=["rast","vect"])

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:

       grass.run_command("r.info", flags="eg", map=["elevation"])

Differences between run_command() and read_command():

• script.core.run_command() executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
• 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.:

def read2_command(*args, **kwargs):
   kwargs['stdout'] = grass.PIPE
   kwargs['stderr'] = grass.PIPE
   ps = grass.start_command(*args, **kwargs)
   return ps.communicate()

This behaves like read_command() 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"):

       grass.run_command('g.copy', rast = (input, output))

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

       grass.run_command('g.copy', **{datatype: (input, output)})

Interface to listing maps (g.list)

You may use the functions in python.script.core.mlist_grouped():

list_grouped('raster')['PERMANENT']
[..., 'lakes', ..., 'slope', ...

and

mlist_grouped('vector', pattern='*roads*')['PERMANENT']
['railroads', 'roadsmajor']

See also Sample PyGRASS scripts for an alternative solution.

i.group with patterns as name for input

Imagery groups can be populated like this:

from grass.pygrass.gis import Mapset

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

Percentage output for progress of computation

A) Within a Python script, the script.core.percent() module method wraps the g.message -p command.

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

       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()

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):

       p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)

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":

       $ r.mapcalc 'foo = null()'
       $ r.info -r foo
       min=NULL
       max=NULL

Using the Python API, The 'min' and 'max' values in the result of the script.raster.raster_info() function will be None.

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 r.info approach only needs to read the metadata files.

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

A count loop:

       while grass.raster_info(inmap)['max'] is not None:
           ...

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:

       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)

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:

       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')

Parse the GRASS GIS version or revision or path to library

In order to a avoid hardcoded versions or to scan the SVN revision of the GRASS GIS version used, you can query the helptext:

Variant 1 (pure Python solution) - svn_revision:

import subprocess
cmd = subprocess.Popen('grass76 --config svn_revision', shell=True, stdout=subprocess.PIPE)
revision = cmd.communicate()[0].rstrip()
print(revision)
# the result is for example: '72327'.

Variant 2 (GRASS GIS-Python solution) - svn_revision:

import subprocess
import grass.script as grass
cmd = grass.Popen('grass76 --config svn_revision', shell=True, stdout=subprocess.PIPE)
revision = cmd.communicate()[0].rstrip()
print(revision)
# the result is for example: '72327'.

Path to GRASS GIS library (GRASS GIS-Python solution):

import subprocess
import grass.script as grass
cmd = grass.Popen('grass76 --config path', shell=True, stdout=subprocess.PIPE)
version = cmd.communicate()[0].rstrip()
print(version)
# the result is for example: '/usr/local/grass-7.6.svn'

Creating a new location

Use 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 script.core.run_command() or 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.:

       grass.run_command('r.resamp.bspline', lambda_ = ...)

Note that this follows Python PEP8 style guide. In GRASS GIS version 6, you have to prepend the underscore.

Controlling the PNG display driver

Code fragment to control the pngdriver in 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')

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:

       import atexit, sys
       import grass.script as grass

       tmp_rast = []

       def cleanup():
           for rast in tmp_rast:
               grass.run_command("g.remove",
                                 flags = 'f',
                                 type = 'raster',
                                 name = 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())

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 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 script.core.use_temp_region()

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()

• 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 script.core.region_env().

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)

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.

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