1Interface to GRASS GIS modules
2==============================
3
4In :mod:`~pygrass.modules` module, GRASS GIS modules are represented
5by :class:`~pygrass.modules.interface.module.Module` class
6objects. These objects are generated based on the XML module
7description that is used also for the generation of the graphical user
8interface (GUI). ::
9
10    >>> from grass.pygrass.modules import Module
11    >>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
12    ...                        slope='slp',  aspect='asp',
13    ...                        format='percent', overwrite=True)
14
15
16It is possible to create a run-able module object and run it later (this
17is also needed for registering GRASS GIS commands with more than one dot
18in their name, e.g. r.slope.aspect):
19
20    >>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
21    ...                        slope='slp',  aspect='asp',
22    ...                        format='percent', overwrite=True, run_=False)
23
24Then we can run the module with: ::
25
26    >>> slope_aspect()
27
28or using the run method: ::
29
30   >>> slope_aspect.run()
31
32
33It is possible to initialize a module, and give the parameters later: ::
34
35    >>> slope_aspect = Module("r.slope.aspect")
36    >>> slope_aspect(elevation='elevation', slope='slp',  aspect='asp',
37    ...              format='percent', overwrite=True)
38
39
40Create the module object input step by step and run later: ::
41
42    >>> slope_aspect = Module("r.slope.aspect")
43    >>> slope_aspect.inputs['elevation']
44    Parameter <elevation> (required:yes, type:raster, multiple:no)
45    >>> slope_aspect.inputs["elevation"].value = "elevation"
46    >>> slope_aspect.inputs["format"]
47    Parameter <format> (required:no, type:string, multiple:no)
48    >>> print slope_aspect.inputs["format"].__doc__
49    format: 'degrees', optional, string
50        Format for reporting the slope
51        Values: 'degrees', 'percent'
52    >>> slope_aspect.inputs["format"].value = 'percents'
53    Traceback (most recent call last):
54        ...
55    ValueError: The Parameter <format>, must be one of: ['degrees', 'percent']
56    >>> slope_aspect.inputs["format"].value = 'percent'
57    >>> slope_aspect.flags = "g"
58    Traceback (most recent call last):
59        ...
60    ValueError: Flag not valid, valid flag are: ['a']
61    >>> slope_aspect.flags = "a"
62    >>> slope_aspect.flags_dict['overwrite']
63    Flag <overwrite> (Allow output files to overwrite existing files)
64    >>> slope_aspect.flags_dict['overwrite'].value = True
65    >>> slope_aspect()
66
67
68
69It is possible to access the module descriptions (name, one line description,
70keywords, label) with:
71
72    >>> slope_aspect.name
73    'r.slope.aspect'
74    >>> slope_aspect.description
75    'Aspect is calculated counterclockwise from east.'
76    >>> slope_aspect.keywords
77    'raster, terrain'
78    >>> slope_aspect.label
79    'Generates raster maps of slope, aspect, curvatures and partial derivatives from a elevation raster map.'
80
81and get the module documentation with: ::
82
83    >>> print slope_aspect.__doc__
84    r.slope.aspect(elevation=elevation, slope=None, aspect=None
85                   format=percent, prec=None, pcurv=None
86                   tcurv=None, dx=None, dy=None
87                   dxx=None, dyy=None, dxy=None
88                   zfactor=None, min_slp_allowed=None)
89    <BLANKLINE>
90    Parameters
91    ----------
92    <BLANKLINE>
93    <BLANKLINE>
94    elevation: required, string
95        Name of input elevation raster map
96    slope: optional, string
97        Name for output slope raster map
98    aspect: optional, string
99        Name for output aspect raster map
100    format: 'degrees', optional, string
101        Format for reporting the slope
102        Values: 'degrees', 'percent'
103    prec: 'float', optional, string
104        Type of output aspect and slope maps
105        Values: 'default', 'double', 'float', 'int'
106    pcurv: optional, string
107        Name for output profile curvature raster map
108    tcurv: optional, string
109        Name for output tangential curvature raster map
110    dx: optional, string
111        Name for output first order partial derivative dx (E-W slope) raster map
112    dy: optional, string
113        Name for output first order partial derivative dy (N-S slope) raster map
114    dxx: optional, string
115        Name for output second order partial derivative dxx raster map
116    dyy: optional, string
117        Name for output second order partial derivative dyy raster map
118    dxy: optional, string
119        Name for output second order partial derivative dxy raster map
120    zfactor: 1.0, optional, float
121        Multiplicative factor to convert elevation units to meters
122    min_slp_allowed: optional, float
123        Minimum slope val. (in percent) for which aspect is computed
124    <BLANKLINE>
125    Flags
126    ------
127    <BLANKLINE>
128    a: None
129        Do not align the current region to the elevation layer
130    overwrite: None
131        Allow output files to overwrite existing files
132    verbose: None
133        Verbose module output
134    quiet: None
135        Quiet module output
136
137
138
139For each input and output parameter it is possible to obtain specific
140information. To see all module inputs, just type: ::
141
142    >>> slope_aspect.inputs #doctest: +NORMALIZE_WHITESPACE
143    TypeDict([('elevation', Parameter <elevation> (required:yes, type:raster, multiple:no)), ('format', Parameter <format> ...)])
144
145To get information for each parameter: ::
146
147    >>> slope_aspect.inputs["elevation"].description
148    'Name of input elevation raster map'
149    >>> slope_aspect.inputs["elevation"].type
150    'raster'
151    >>> slope_aspect.inputs["elevation"].typedesc
152    'string'
153    >>> slope_aspect.inputs["elevation"].multiple
154    False
155    >>> slope_aspect.inputs["elevation"].required
156    True
157
158Or get a small documentation for each parameter with:
159
160    >>> print slope_aspect.inputs["elevation"].__doc__
161    elevation: required, string
162        Name of input elevation raster map
163
164
165User or developer can check which parameters have been set, with: ::
166
167    if slope_aspect.outputs['aspect'].value == None:
168        print "Aspect is not computed"
169
170
171After we set the parameters, we can run the module in the background with
172`finish_=False`. Then call `wait()` and retrieve the returncode. ::
173
174    >>> slope_aspect = Module('r.slope.aspect')
175    >>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
176    >>> slope_aspect.wait()
177    Module('r.slope.aspect')
178    >>> slope_aspect.returncode
179    0
180
181
182Another example of use: ::
183
184    >>> from subprocess import PIPE
185    >>> info = Module("r.info", map="elevation", flags="r", stdout_=PIPE)
186    >>> from grass.script.utils import parse_key_val
187    >>> parse_key_val(info.outputs.stdout)
188    {'max': '156.3299', 'min': '55.57879'}
189
190
191Launching GRASS GIS modules in parallel
192---------------------------------------
193
194PyGRASS implements simple mechanism for launching GRASS modules in
195parallel. See
196:class:`~pygrass.modules.interface.module.ParallelModuleQueue` class
197for details.
198
199Multiple GRASS modules can be joined into one object by
200:class:`~pygrass.modules.interface.module.MultiModule`.
201
202
203.. _Popen: http://docs.python.org/library/subprocess.html#Popen
204