GRASS-Wiki - User contributions [en]

R.basin

2012-06-21T22:19:01Z

⚠️Jentjr: /* Preparation */

== Introduction ==

The module {{AddonCmd|r.basin}} has been designed to perform the delineation and the morphometric characterization of a given basin, on the basis of an elevation raster map and the coordinates of the outlet.
Please note that it is designed to work only in projected coordinates.
Here a tutorial based on NC sample dataset is presented.

== Preparation ==

As a first step, we set the computational region to match the elevation raster map:

<pre>
g.region rast=elevation@PERMANENT -ap
projection: 99 (Lambert Conformal Conic)
zone: 0
datum: nad83
ellipsoid: a=6378137 es=0.006694380022900787
north: 228500
south: 215000
west: 630000
east: 645000
nsres: 10
ewres: 10
rows: 1350
cols: 1500
cells: 2025000
</pre>

For the basin's delineation, a pair of coordinates is required. Usually coordinates belonging to the natural river network don't exactly match with the calculated stream network. What we should do is calculate the stream network first, and then find the coordinates on the calculated stream network closest to the coordinates belonging to the natural stream network.

<pre>
# Calculate flow accumulation map
r.watershed -a elevation=elevation@PERMANENT accumulation=accum

# Extract the stream network
r.stream.extract elevation=elevation@PERMANENT accumulation=accum@testing threshold=20 stream_rast=stream_network stream_vect=streams
</pre>

We no longer need the accumulation map:

<pre>
g.remove rast=accum
</pre>

Now that we have the calculated stream network, we should choose a pair of coordinates for the outlet belonging to it. Let's choose:

<pre>
easting=636654.791181 northing=218824.126649
</pre>

We no longer need the stream network map:

<pre>
g.remove rast=stream_network
</pre>

== Preparation for multiple basins' analysis ==

If there are a lot of basins to be analysed, the coordinate pairs of the intersections between the calculated stream network and basins (outlet points) can be found by:

<pre>
# Convert basins polygon vector boundaries to lines
v.type input=basinspoly output=basinsline type=boundary,line

# Patch basins lines with stream network
v.patch input=basinsline,streams output=basins_streams

# Find cross points at intersections
v.clean input=basins_streams output=basins_streams_clean error=crosspoints_err tool=break

# Add categories to cross points vector
v.category input=crosspoints_err output=crosspoints

# Add table to cross points vector with columns for category, x and y coordinates
v.db.addtable map=crosspoints columns="cat integer,xcoor double precision, ycoor double precision"

# Upload category to cross points attribute table
v.to.db map=crosspoints option=cat columns=cat

# Upload x and y coordinates to cross points attribute table
v.to.db map=crosspoints option=coor columns=xcoor,ycoor
</pre>

At this point we can create a text file called ''crosspoints'' with the coordinates in this form:

<pre>
xcoor1 ycoor1
xcoor2 ycoor2
xcoor3 ycoor3
...
</pre>

Now we can parse this coordinates file in order to create a new file called ''commands'' in which we'll have the r.basin commands for each sub-watershed, ready to be run in a GRASS session. Let's create a script in python for parsing:

<pre>
#!/usr/bin/env python

# Open the ''crosspoints'' text file to read the coordinates
fin = open("crosspoints","r")

# Create the ''commands'' text file
fout = open("commands","w")

# Read the ''crosspoints'' lines
linesout = (line.rstrip().split() for line in fin)

# Build the r.basin command
# Put your threshold parameter instead of threshold=10000 and the name of your DEM instead of map=elevation
cmd = 'r.basin map=elevation prefix=bas%s easting=%s northing=%s threshold=10000\n'

# Write the file ''commands''
fout.writelines(cmd % (n, easting, northing) for n,(easting,northing) in enumerate(linesout))
</pre>

This is a Python script, it is supposed to run externally from GRASS GIS. Save this script as ''parsing.py'' in a separate folder on your Desktop, and put the file ''crosspoints'' in such folder. To run it, open a terminal and type:

<pre>
cd yourfolder
python parsing.py
</pre>

Now in the same folder you will find the file ''commands'', in which we have the r.basin commands to run in GRASS.

== Usage ==

We can run r.basin:

<pre>
r.basin map=elevation@PERMANENT prefix=out easting=636654.791181 northing=218824.126649 threshold=20
</pre>

Prefix parameter is a string given by the user in order to distinguish all the maps produced by every run of the program, i.e. every set of outlet's coordinates. Prefix must start with a letter.

Threshold is the same parameter given in r.watershed and r.stream.extract. Physically, it means the number of cells that determine "where the river begins". (This is an open issue for the hydrological science and a wide literature has been produced on the topic). Threshold value is usually determined by trials and errors. r.basin has a flag -a, which uses an authomatic value of threshold, corresponding to 1km^2. Such value comes from literature and is usually suitable for Italian territory, but could be definitely wrong for other territories.
In order to determine the threshold, see also {{AddonCmd|r.threshold}} and {{AddonCmd|r.stream.preview}}.

The output of r.basin consists of:

* Several morphometric parameters, which are printed in terminal and also stored in a csv file called out_elevation_parameters.csv, in the working directory;
* Maps;
* Plots.

== Morphometric parameters ==

The main parameters are:

* The coordinates of the vertices of the '''rectangle containing the basin'''.
* The '''center of gravity''' of the basin: the coordinates of the pixel nearest to the center of gravity of the geometric figure resulting from the projection of the basin on the horizontal plane.
* The '''area''' of the basin: is the area of a single cell multiplied by the number of cells belonging to the basin.
* The '''perimeter''': is the length of the contour of the figure resulting by the projection of the basin on the horizontal plane.
[As a side note, a paper namely [http://en.wikipedia.org/wiki/How_Long_Is_the_Coast_of_Britain%3F_Statistical_Self-Similarity_and_Fractional_Dimension "How Long Is the Coast of Britain? Statistical Self-Similarity and Fractional Dimension"] points out that perimeter is affected by a fractal problem and the number is mostly meaningless taken by itself. Hence, perimeter should never be mixed with anything from another dataset or even the same data set at a different cell resolution; it is only good as a percentage comparison to its neighbors in the same dataset].
* '''Characteristic values of elevation''': the highest and the lowest altitude, the difference between them and the mean elevation calculated as the sum of the values of the cells divided by the number of the cells.
* The '''mean slope''', calculated averaging the slope map.
* The '''length of the directing vector''': the length of the vector linking the outlet to the center of gravity of the basin.
* The '''prevalent orientation''': in GRASS the aspect categories represent the number degrees of east and they increase counterclockwise: (90deg is North, 180 is West, 270 is South 360 is East). The aspect value 0 is used to indicate undefined aspect in flat areas with slope=0. We instead calculate the orientation as the number of degree from north, increasing counterclockwise.
* The '''length of main channel''': is the length of the longest succession of segments that connect a source to the outlet of the basin.
* The '''mean slope of main channel''': it is calculated as follows:

<center>
[[File:R.basin1.gif]]
</center>

where N is the topological diameter, i.e. the number of links in which the main channel can be divided on the basis of the junctions.
* The '''circularity ratio''': is the ratio between the area of the basin and the area of the circle having the same perimeter of the basin.
* The '''elongation ratio''': is the ratio between the diameter of the circle having the same area of the basin and the length of the main channel.
* The '''compactness coefficient''': is the ratio between the perimeter of the basin and the diameter of the circle having the same area of the basin.
* The '''shape factor''': is the ratio between the area of the basin and the square of the length of the main channel.
* The '''concentration time''' (Giandotti, 1934):

<center>
[[File:R.basin2.gif]]
</center>

Where A is the area, L the length of the main channel and H the difference between the highest and the lowest elevation of the basin.
* The '''mean hillslope length''': is the mean of the distances calculated along the flow direction of each point non belonging to the river network from the point in which flows into the network.
* The '''magnitudo''': is the number of the branches of order 1 following the Strahler hierarchy.
* The '''max order''': is the order of the basin, following the Strahler hierarchy.
* The '''number of streams''': is the number of the branches of the river network.
* The '''total stream length''': is the sum of the length of every branches.
* The '''first order stream frequency''': is the ratio between the magnitudo and the area of the basin.
* The '''drainage density''': is the ratio between the total length of the river network and the area.
* The '''Horton ratios''' (Horton, 1945; Strahler, 1957).

<pre>
##################################
Morphometric parameters of basin :
##################################
Easting Centroid of basin : 635195.00
Northing Centroid of Basin : 220715.00
Rectangle containing basin N-W : 632870 , 222890
Rectangle containing basin S-E : 637000 , 218720
Area of basin [km^2] : 7.8559625
Perimeter of basin [km] : 16.8287990515
Max Elevation [m s.l.m.] : 151.7396
Min Elevation [m s.l.m.]: 94.82206
Elevation Difference [m]: 56.91754
Mean Elevation [m s.l.m.]: 127.6772
Mean Slope : 2.93
Length of Directing Vector [km] : 2.38880562659
Prevalent Orientation [degree from north, counterclockwise] :
0.913351005341
Compactness Coefficient : 5.32106255399
Circularity Ratio : 0.348580442132
Topological Diameter : 127.0
Elongation Ratio : 0.470961456397
Shape Factor : 1.16984953656
Concentration Time (Giandotti, 1934) [hr] : 3.52654267443
Length of Mainchannel [km] : 6.715361467
Mean slope of mainchannel [percent] : 0.957339
Mean hillslope length [m] : 8145.381
Magnitudo : 621.0
Max order (Strahler) : 5
Number of streams : 884
Total Stream Length [km] : 96.3436
First order stream frequency : 79.0482388377
Drainage Density [km/km^2] : 12.2637550778
Bifurcation Ratio (Horton) : 5.7374
Length Ratio (Horton) : 2.6902
Area ratio (Horton) : 5.6815
Slope ratio (Horton): 1.5533
</pre>

The '''hypsographic curve''' provides the distribution of the areas at different altitudes. Each point on the hypsographic curve has on the y-axis the altitude and on the x-axis the percentage of basin surface placed above that altitude. The '''ipsometric curve''' has the same shape but is dimensionless.
Quantiles of the ipsometric curve are displayed:

<pre>
Tot. cells 78560.0
===========================
Ipsometric | quantiles
===========================
145 | 0.025
143 | 0.05
141 | 0.1
137 | 0.25
129 | 0.5
119 | 0.75
121 | 0.7
110 | 0.9
100 | 0.975
</pre>

The '''width function W(x)''' gives the area of the cells in the basin at a certain flow distance x from the outlet (distance-area function). Note that the distance is not intended in the euclidean sense, but it's calculated considering the hydrological path of the water.

<pre>
Tot. cells 78560.0
Tot. area 7856000.0
Max distance 6809.546521
===========================
Whidth Function | quantiles
===========================
784 | 0.05
1477 | 0.15
2137 | 0.3
2543 | 0.4
2933 | 0.5
3606 | 0.6
4169 | 0.7
5144 | 0.85
6105 | 0.95
</pre>

The output of r.stream.stats is also displayed:

<pre>
Summary:
Max order | Tot.N.str. | Tot.str.len. | Tot.area. | Dr.dens. | Str.freq.
(num) | (num) | (km) | (km2) | (km/km2) | (num/km2)
5 | 884 | 96.3436 | 7.8339 | 12.2983 | 112.8429

Stream ratios with standard deviations:
Bif.rt. | Len.rt. | Area.rt. | Slo.rt. | Grd.rt.
5.7374 | 2.6902 | 5.6815 | 1.5533 | 1.7962
3.1961 | 1.9514 | 5.2294 | 0.1250 | 0.7482

Order | Avg.len | Avg.ar | Avg.sl | Avg.grad. | Avg.el.dif
num | (km) | (km2) | (m/m) | (m/m) | (m)
1 | 0.0750 | 0.0069 | 0.0523 | 0.0384 | 3.1062
2 | 0.1428 | 0.0311 | 0.0342 | 0.0277 | 4.1701
3 | 0.4834 | 0.1732 | 0.0243 | 0.0205 | 9.0641
4 | 2.4205 | 2.1885 | 0.0155 | 0.0134 | 24.1708
5 | 1.1247 | 7.8339 | 0.0091 | 0.0046 | 5.1594

Order | Std.len | Std.ar | Std.sl | Std.grad. | Std.el.dif
num | (km) | (km2) | (m/m) | (m/m) | (m)
1 | 0.0600 | 0.0052 | 0.0398 | 0.0287 | 3.2301
2 | 0.1244 | 0.0230 | 0.0250 | 0.0196 | 4.4835
3 | 0.4554 | 0.1353 | 0.0132 | 0.0122 | 7.1065
4 | 2.2874 | 2.3843 | 0.0046 | 0.0061 | 12.9175
5 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0000

Order | N.streams | Tot.len (km) | Tot.area (km2)
1 | 712 | 53.4067 | 4.8998
2 | 137 | 19.5657 | 4.2562
3 | 31 | 14.9849 | 5.3684
4 | 3 | 7.2616 | 6.5655
5 | 1 | 1.1247 | 7.8339

Order | Bif.rt. | Len.rt. | Area.rt. | Slo.rt. | Grd.rt. | d.dens. | str.freq.
1 | 5.1971 | 1.9040 | 0.0000 | 1.5311 | 1.3892 | 10.8998 | 145.3120
2 | 4.4194 | 3.3847 | 4.5144 | 1.4046 | 1.3472 | 4.5970 | 32.1883
3 | 10.3333 | 5.0075 | 5.5742 | 1.5691 | 1.5365 | 2.7913 | 5.7745
4 | 3.0000 | 0.4646 | 12.6376 | 1.7083 | 2.9120 | 1.1060 | 0.4569
5 | 0.0000 | 0.0000 | 3.5796 | 0.0000 | 0.0000 | 0.1436 | 0.1277
</pre>

== Maps ==

Since r.basin performs the delimitation of the river basin, all the maps produced are cropped over the basin. They are:

* Raster maps

<pre>
g.list rast

out_elevation_accumulation out_elevation_hillslope_distance
out_elevation_aspect out_elevation_horton
out_elevation_dist2out out_elevation_shreve
out_elevation_drainage out_elevation_slope
out_elevation_hack out_elevation_strahler

</pre>

<center>
<gallery perrow=3 widths=200>

File:Out_elevation_accumulation.png|Flow accumulation
File:Out_elevation_aspect.png|Aspect
File:Out_elevation_dist2out.png|Distance to outlet (width function)
File:Out_elevation_drainage.png|Flow direction
File:Out_elevation_hack.png|Stream network ordered according to Hack
File:Out_elevation_hillslope_distance.png|Length of hillslopes
File:Out_elevation_horton.png|Stream network ordered according to Horton
File:Out_elevation_shreve.png|Stream network ordered according to Shreve
File:Out_elevation_slope.png|Slope
File:Out_elevation_strahler.png|Stream network ordered according to Strahler

</gallery>
</center>

* Vector maps

<pre>
g.list vect

out_elevation_basin out_elevation_network
out_elevation_mainchannel out_elevation_outlet
</pre>

<center>
<gallery perrow=4 widths=200>

File:Out_elevation_basin.png|Basin
File:Out_elevation_mainchannel.png|Main channel
File:Out_elevation_network.png|Stream network
File:Out_elevation_outlet.png|Outlet

</gallery>
</center>

== Plots ==

Plots are stored in the working directory:

* out_elevation_ipsographic.png
* out_elevation_ipsometric.png
* out_elevation_width_function.png

<center>
<gallery perrow=3 widths=200>

File:Out_elevation_Ipsographic.png|Ipsographic curve
File:Out_elevation_Ipsometric.png|Ipsometric curve (Nondimensional ipsographic curve)
File:Out_elevation_width_function.png|Width function

</gallery>
</center>

== See also ==

[[R.stream.*]]

== References ==

* Di Leo Margherita, Working report: Extraction of morphometric parameters from a digital elevation model - Panama. North Carolina State University, 2010 ([http://dl.dropbox.com/u/1599323/Report_Panama.pdf PDF])
* Rodriguez-Iturbe I., Rinaldo A.; Fractal River Basins, Chance and Self-Organization. Cambridge Press, 2001.
* Di Leo M., Di Stefano M., Claps P., Sole A. Caratterizzazione morfometrica del bacino idrografico in GRASS GIS (Morphometric characterization of the catchment in GRASS GIS environment), Geomatics Workbooks n.9, 2010. ([http://geomatica.como.polimi.it/workbooks/n9/GW9-FOSS4Git_2010.pdf PDF]).

[[Category: Documentation]]
[[Category: Hydrology]]

GRASS messages translation

2012-06-19T19:37:47Z

⚠️Jentjr:

== Help page translations ==

* For translations of full help (man) pages see [[Updating GRASS Documentation#Translations]]

== GRASS messages translation project ==

Many users prefer to use software in their mother tongue which is mostly not English. This requires that all GRASS software messages have to be translated to languages other than English. The GRASS Development Team is seeking translators. Please subscribe to the dedicated mailing list at

GRASS translations mailing list
http://lists.osgeo.org/mailman/listinfo/grass-translations

Translation related issues may be discussed there. This is an opportunity for non-programmers to contribute as messages can be easily translated. No programming skills required!

* Join the [[GRASS_Translation_Team#Members_of_Translation_Team|team]]

=== Wanted languages ===

Simple Chinese, Swahili, Hindi, Greek, Tamil, Russian, Telugu, Português, ... Please join us!

== How to change the language ==

* see [[GRASS_messages_translation#Testing_different_languages|Testing different languages]] below.

== How to create new translations ==

* For terminology, please refer to the [[GRASS Translation Glossary]].

=== Files ===
In GRASS, we have 4 types of .po files per language (see in the source code the directory locale/po/):

* <tt>grasslibs_LANG.po</tt>: messages from libraries
* <tt>grassmods_LANG.po</tt>: messages from commands ("modules")
* <tt>grassnviz_LANG.po</tt>: messages from NVIZ Tcl/Tk graphical user interface (GRASS 6)
* <tt>grasstcl_LANG.po</tt>: messages from Tcl/Tk graphical user interface (GRASS 6)
* <tt>grasswxpy_LANG.po</tt>: messages from wxgrass/wxPython graphical user interface

where "LANG" in the above file names is a two character code which indicates the language. It is based on the Alpha-2 code of [http://www.loc.gov/standards/iso639-2/php/English_list.php ISO 639-1] (right column). Example: <tt>grasswxpy_pl.po</tt> for Polish.

=== Continuing an existing translation ===

The file(s) are there but partially outdated? Read on.

First '''announce''' on the [http://lists.osgeo.org/mailman/listinfo/grass-translations GRASS translations mailing list] that you plan to continue the translation of a certain language. Why? Because sometimes people silently translate already and we need these efforts to be coordinated to avoid doing it twice...

Then get these four .po files for your language and start. If a file is missing, just ask on the list to get it generated or see next section. To get these .po files (the files are in the directory locale/po/):

* either [http://svn.osgeo.org/grass/grass/branches/releasebranch_6_4/locale/po/ download current .po files] directly from SVN (click on file name to download),
* or [http://trac.osgeo.org/grass/wiki/DownloadSource#GRASS6.4 download source code package] from SVN,
* or download the recent [http://grass.osgeo.org/grass64/source/snapshot/ source code snapshot],
* or ask on the [http://lists.osgeo.org/mailman/listinfo/grass-translations GRASS translations mailing list] for these files.

Then edit the files with a .po file editor (poEDIT or kbabel or..., see below). Take care to maintain layout and special characters. And '''submit often''' - if you wait for weeks, the messages may already be outdated and your time wasted. Just keep in touch on the [http://lists.osgeo.org/mailman/listinfo/grass-translations GRASS translations mailing list]!

=== Starting a new translation ===

The language you want isn't yet there? Read on.

Briefly, the steps to create new messages files are (if you find this too complicated, ask on the [http://lists.osgeo.org/mailman/listinfo/grass-translations GRASS translations mailing list] to get these files done for you!):

# Get the latest source code development version from either the SVN repository or as SVN snapshot (see [http://grass.osgeo.org/download/index.php Download]).
# run: './configure --with-nls [... other parameters]' to configure the GRASS source code
# run: 'cd locale' to change into the translation directory
# run: 'make pot' to create grass*.pot template files (to extract original messages)
# run: copy these file from templates/ into po/; rename them to contain the two characters language code (see Alpha-2 code of [http://www.loc.gov/standards/iso639-2/php/English_list.php ISO 639-1]) and to .po extension; update the file headers either manually or with your .po editing software
(Example: Polish language):
mv ./templates/grasslibs.pot ./po/grasslibs_pl.po
mv ./templates/grassmods.pot ./po/grassmods_pl.po
mv ./templates/grassnviz.pot ./po/grassnviz_pl.po
mv ./templates/grasstcl.pot ./po/grasstcl_pl.po
mv ./templates/grasswxpy.pot ./po/grasswxpy_pl.po

Now translate the messages in these po/*.po files (using poEDIT or other editor, see below)

From time to time messages need to be updated from the originals. This is usually done by the GRASS translation manager.

== Software to translate: .po file editors ==

* [http://userbase.kde.org/Lokalize Lokalize]: (previously KBabel) is a set of tools for editing and managing gettext PO files, cross-platform, comes with KDE SC (works also under MS-Windows)
* [http://www.poedit.net/download.php poEdit]: poEdit is gettext catalogs (.po files) editor (works also under MS-Windows)
* [http://translate.sourceforge.net/wiki/virtaal/index Virtaal] Virtaal is cross-platform graphical translation tool with terminology help from [http://open-tran.eu Open-Tran.eu]
* [https://www.transifex.net/projects/p/grass6/ Web based solution Transifex] (''help needed to revive'')
* [http://www.omegat.org/ Java based solution OmegaT]

'''How to use Transifex to translate messages online in a browser:'''
* (''currently offline due to 2011 transifex website transition. please contact the translations mailing list (or Markus N) if you'd like to help with that'')

[[Image:Transifex register signin.png|center|450px|Register and sign in]]

[[Image:Transifex edit online.png|center|450px|Click to edit online]]

== Testing different languages ==

Testing different languages requires that the respective language environment and, if needed, fonts are installed.
Check what languages are currently installed on your system with:
locale -a

To change to a certain language environment (locale), do the following steps (here, example for Unix style environment):

1. Define/check language settings:
echo $LANG
echo $LANGUAGE
echo $LC_MESSAGES

2. Change it (example for to Japanese):
a) bash shell:
export LANG=ja_JP.UTF-8
export LANGUAGE=ja_JP.UTF-8
export LC_MESSAGES=ja_JP.UTF-8

b) (t)csh shell:
setenv LANG ja_JP.UTF-8
setenv LANGUAGE ja_JP.UTF-8
setenv LC_MESSAGES ja_JP.UTF-8

Now launch GRASS in this terminal. If you launch it from an icon, you have to change the LOCALE in the computer setup program instead.

Other common languages useful for testing are <tt>de_DE</tt> for German, <tt>fr_FR</tt> for French, or "C" for none (effectively <tt>en_US</tt>, which for GRASS is the base language).

=== Creating startup scripts for different languages ===

GRASS in English language, save as "grass64eng" (executable flag set, store in path):
#!/bin/sh
export LANG=en_US
export LANGUAGE=en_US
export LC_MESSAGES=en_US
exec grass64 "$@"

GRASS in Japanese language, save as "grass64ja" (executable flag set, store in path):
#!/bin/sh
export LANG=ja_JA.UTF-8
export LANGUAGE=ja_JA.UTF-8
export LC_MESSAGES=ja_JA.UTF-8
grass64 "$@"

== Coordination among translators ==

If several translators work on the same language files, obviously some coordination is needed. Please announce work via the "translations" mailing list at http://lists.osgeo.org/mailman/listinfo/grass-translations

Also the translation manager is listening there to the upload the changed files into the GRASS source code repository.

== Best practices ==

* Italiano: [http://tp.linux.it/buona_traduzione.html Regole per la buona traduzione]

== Installation of language packages ==

Example: Chinese

* Mandriva: urpmi locales-zh kde-l10n-zh_CN fonts-ttf-default-zh_CN

[[Category: Development]]
[[Category: Documentation]]
[[Category: FAQ]]