ModulesΒΆ

Grass modules are represented as objects. These objects are generated based on the XML module description that is used for GUI generation already.

>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
...                        slope='slp',  aspect='asp',
...                        format='percent', overwrite=True)

It is possible to create a run-able module object and run later:

>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
...                        slope='slp',  aspect='asp',
...                        format='percent', overwrite=True, run_=False)

Then we can run the module with:

>>> slope_aspect()

or using the run method:

>>> slope_aspect.run()

It is possible to initialize a module, and give the parameters later:

>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp',  aspect='asp',
...              format='percent', overwrite=True)

Create the module object input step by step and run later:

>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect.inputs['elevation']
Parameter <elevation> (required:yes, type:raster, multiple:no)
>>> slope_aspect.inputs["elevation"].value = "elevation"
>>> slope_aspect.inputs["format"]
Parameter <format> (required:no, type:string, multiple:no)
>>> print slope_aspect.inputs["format"].__doc__
format: 'degrees', optional, string
    Format for reporting the slope
    Values: 'degrees', 'percent'
>>> slope_aspect.inputs["format"].value = 'percents'
Traceback (most recent call last):
    ...
ValueError: The Parameter <format>, must be one of: ['degrees', 'percent']
>>> slope_aspect.inputs["format"].value = 'percent'
>>> slope_aspect.flags = "g"
Traceback (most recent call last):
    ...
ValueError: Flag not valid, valid flag are: ['a']
>>> slope_aspect.flags = "a"
>>> slope_aspect.flags_dict['overwrite']
Flag <overwrite> (Allow output files to overwrite existing files)
>>> slope_aspect.flags_dict['overwrite'].value = True
>>> slope_aspect()

It is possible to access to the module info, with:

>>> slope_aspect.name
'r.slope.aspect'
>>> slope_aspect.description
'Aspect is calculated counterclockwise from east.'
>>> slope_aspect.keywords
'raster, terrain'
>>> slope_aspect.label
'Generates raster maps of slope, aspect, curvatures and partial derivatives from a elevation raster map.'

and get the module documentation with:

>>> print slope_aspect.__doc__
r.slope.aspect(elevation=elevation, slope=None, aspect=None
               format=percent, prec=None, pcurv=None
               tcurv=None, dx=None, dy=None
               dxx=None, dyy=None, dxy=None
               zfactor=None, min_slp_allowed=None)

Parameters
----------


elevation: required, string
    Name of input elevation raster map
slope: optional, string
    Name for output slope raster map
aspect: optional, string
    Name for output aspect raster map
format: 'degrees', optional, string
    Format for reporting the slope
    Values: 'degrees', 'percent'
prec: 'float', optional, string
    Type of output aspect and slope maps
    Values: 'default', 'double', 'float', 'int'
pcurv: optional, string
    Name for output profile curvature raster map
tcurv: optional, string
    Name for output tangential curvature raster map
dx: optional, string
    Name for output first order partial derivative dx (E-W slope) raster map
dy: optional, string
    Name for output first order partial derivative dy (N-S slope) raster map
dxx: optional, string
    Name for output second order partial derivative dxx raster map
dyy: optional, string
    Name for output second order partial derivative dyy raster map
dxy: optional, string
    Name for output second order partial derivative dxy raster map
zfactor: 1.0, optional, float
    Multiplicative factor to convert elevation units to meters
min_slp_allowed: optional, float
    Minimum slope val. (in percent) for which aspect is computed

Flags
------

a: None
    Do not align the current region to the elevation layer
overwrite: None
    Allow output files to overwrite existing files
verbose: None
    Verbose module output
quiet: None
    Quiet module output

For each inputs and outputs parameters it is possible to get info, to see all the module inputs, just type:

>>> slope_aspect.inputs 
TypeDict([('elevation', Parameter <elevation> (required:yes, type:raster, multiple:no)), ('format', Parameter <format> (required:no, type:string, multiple:no)), ('prec', Parameter <prec> (required:no, type:string, multiple:no)), ('zfactor', Parameter <zfactor> (required:no, type:float, multiple:no)), ('min_slp_allowed', Parameter <min_slp_allowed> (required:no, type:float, multiple:no))])

To get info for each parameter:

>>> slope_aspect.inputs["elevation"].description
'Name of input elevation raster map'
>>> slope_aspect.inputs["elevation"].type
'raster'
>>> slope_aspect.inputs["elevation"].typedesc
'string'
>>> slope_aspect.inputs["elevation"].multiple
False
>>> slope_aspect.inputs["elevation"].required
True

Or get a small documentation for each parameter with:

>>> print slope_aspect.inputs["elevation"].__doc__
elevation: required, string
    Name of input elevation raster map

User or developer can check which parameter are set, with:

if slope_aspect.outputs['aspect'].value == None:
    print "Aspect is not computed"

After we set the parameter and run the module, the execution of the module instantiate a popen attribute to the class. The Popen class allow user to kill/wait/ the process.

>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
>>> print err 
 100%
Aspect raster map <asp> complete
Slope raster map <slp> complete

On the above example we use a new parameter finish_, if is set to True, the run method, automatically store the stdout and stderr to stdout and stderr attributes of the class:

>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=True)
>>> print slope_aspect.stderr 
 100%
Aspect raster map <asp> complete
Slope raster map <slp> complete

Another example of use:

>>> info = Module("r.info", map="elevation", flags="r", finish_=True)
>>> from pygrass.modules import stdout2dict
>>> stdout2dict(info.stdout)
{'max': '156.3299', 'min': '55.57879'}
>>> info = Module("r.info", map="elevation", flags="r", finish_=False)
>>> category = Module("r.category", map="elevation",
...                   stdin_=info.popen.stdout, finish_=True)

Project Versions

Previous topic

Attributes

This Page