| 1 |
<h2>DESCRIPTION</h2> |
| 2 |
|
| 3 |
<em>d.linegraph</em> is a module to draw simple x,y line graphs |
| 4 |
(plots) based on numerical data contained in separate files. |
| 5 |
|
| 6 |
<h3>Data format</h3> |
| 7 |
|
| 8 |
The X and Y data files for the graph are essentially a column of numbers in |
| 9 |
each file, with one input number per line. The program expects that each X |
| 10 |
value will have a corresponding Y value, therefore the number of lines in |
| 11 |
each data input file should be the same. Essentially, the X data becomes |
| 12 |
the X axis reference to which the Y data is plotted as a line. Therefore, |
| 13 |
the X data should be a monotonically increasing progression of numbers (i.e. |
| 14 |
"1,2,3,..."; "0, 10, 100, 1000,..."; "...-5,-1,0,1,5..."). If multiple Y |
| 15 |
data files are used, the Y axis scale will be based on the range of minimum |
| 16 |
and maximum values from all Y files, then all Y data given will be graphed |
| 17 |
according to that Y scale. Therefore, if multiple Y data inputs are used |
| 18 |
with dissimilar units, the graph produced comparing the two will be |
| 19 |
deceptive. |
| 20 |
|
| 21 |
<h3>File inputs</h3> |
| 22 |
|
| 23 |
If the <b>directory</b> option is provided, the paths to files can (and |
| 24 |
should) be only relative paths to these files. While this is not recommended |
| 25 |
for scripting, it can be advantageous when typing the paths |
| 26 |
manually. For example when all files are stored in the directory |
| 27 |
<code>/home/john/data</code>, the user can provide the following in the command |
| 28 |
line: |
| 29 |
|
| 30 |
<div class="code"><pre> |
| 31 |
d.linegraph directory=/home/john/data x_file=x.txt y_file=y1.txt,y2.txt |
| 32 |
</pre></div> |
| 33 |
|
| 34 |
<h3>Managing colors</h3> |
| 35 |
|
| 36 |
The user can specify the <b>y_color</b> option, the <b>color_table</b> |
| 37 |
option or just leave the defaults to influence the color of the |
| 38 |
plotted lines. |
| 39 |
|
| 40 |
<p> |
| 41 |
Colors specified by <b>y_color</b> option are used for drawing the lines |
| 42 |
in the graph. If multiple Y data files are used, an equal number of |
| 43 |
colors may be used to control the colors of the lines. Colors will be |
| 44 |
assigned to Y data in respect to the sequence of instantiation on the |
| 45 |
command line. It can be one of GRASS named colors or the RGB |
| 46 |
values from 0-255 separated by colons (RRR:GGG:BBB). |
| 47 |
|
| 48 |
<p> |
| 49 |
Alternatively, the user can use the <b>color_table</b> option to specify one |
| 50 |
of the GRASS predefined color tables. |
| 51 |
|
| 52 |
<p> |
| 53 |
By default, a series of colors will be chosen by the module if none are |
| 54 |
provided upon invocation. The order of default colors is red, green, |
| 55 |
violet, blue, orange, gray, brown, magenta, white, and indigo. The user is |
| 56 |
advised not to rely on the order of default colors but to either use the |
| 57 |
<b>y_color</b> or the <b>color_table</b> option to obtain predictable and |
| 58 |
reproducible results. |
| 59 |
|
| 60 |
<p> |
| 61 |
The color to be used for titles, axis lines, tics, and scale numbers |
| 62 |
is determined by the <b>title_color</b> option. The user can provide |
| 63 |
one of the GRASS named colors (such as gray, white, or black) |
| 64 |
or use the GRASS colon-separated format for RGB (RRR:GGG:BBB). |
| 65 |
|
| 66 |
<h3>Titles, labels, and tics</h3> |
| 67 |
|
| 68 |
The <b>title</b> option specifies the text for the title of the graph. |
| 69 |
It will be centered over the top of graph. |
| 70 |
|
| 71 |
The <b>x_title</b> option is a text to describe data for X axis. It will be |
| 72 |
centered beneath the graph. Default is no text unless there is a need |
| 73 |
for a unit descriptor determined by the <em>d.linegraph</em> module, |
| 74 |
then string such as "in hundreds" is generated. |
| 75 |
|
| 76 |
The <b>y_title</b> option is a text to describe data for Y axis. It |
| 77 |
will be centered beneath the X data description. Similarly, to the |
| 78 |
<b>x_title</b> option, default is no text unless there is a need for an |
| 79 |
auto-generated description. In the case of graphs with multiple lines |
| 80 |
(multiple inputs for Y axis), user may wish to use more specific text |
| 81 |
placement using the <em><a href="d.text.html">d.text</a></em> or |
| 82 |
<em><a href="v.label.html">v.label</a></em> programs. |
| 83 |
|
| 84 |
<h2>NOTES</h2> |
| 85 |
|
| 86 |
For historical reasons, the <em>d.linegraph</em> module accepts |
| 87 |
titles of more than one word where the underscore character ("_") |
| 88 |
is used to represent spaces (" "). For example "Census_data_1990" would be |
| 89 |
printed over the graph as "Census data 1990". The use of underscores is not |
| 90 |
necessary to use as long as the parameter is quoted in the command line. |
| 91 |
In general, use of underscores is not recommended and there is no need to use |
| 92 |
it at all in the GUI or when using <em>d.linegraph</em> in Python scripts. |
| 93 |
|
| 94 |
<p> |
| 95 |
The way the program locates and labels tic marks is less than perfect: |
| 96 |
<br> |
| 97 |
1) although distances between Y tics are proportional to the value, they are |
| 98 |
not proportional on the X axis; |
| 99 |
<br> |
| 100 |
2) decimal values between -1 and 1 can be printed on the X axis, but not |
| 101 |
on Y. (With respect to the later, the input for Y values can all be |
| 102 |
multiplied by a factor of 10 before graphing). |
| 103 |
|
| 104 |
<p> |
| 105 |
Depending on the user's needs, it might be easier or more appropriate |
| 106 |
to use a 3rd party tool such as xgraph, gnuplot, Matplotlib in Python, |
| 107 |
or R instead of <em>d.linegraph</em>. |
| 108 |
For a more general solution for plotting in GRASS, the user is |
| 109 |
advised to use the <em><a href="d.graph.html">d.graph</a></em> module. |
| 110 |
|
| 111 |
<h2>EXAMPLE</h2> |
| 112 |
|
| 113 |
The following can be executed in Bash to create the input data for this |
| 114 |
example. The user can just create these files in a text editor, save |
| 115 |
them and specify path to them. |
| 116 |
|
| 117 |
<div class="code"><pre> |
| 118 |
cat > x.txt <<EOF |
| 119 |
1 |
| 120 |
3 |
| 121 |
4 |
| 122 |
6 |
| 123 |
9 |
| 124 |
EOF |
| 125 |
cat > y1.txt <<EOF |
| 126 |
50 |
| 127 |
58 |
| 128 |
65 |
| 129 |
34 |
| 130 |
27 |
| 131 |
EOF |
| 132 |
cat > y2.txt <<EOF |
| 133 |
10 |
| 134 |
20 |
| 135 |
35 |
| 136 |
50 |
| 137 |
45 |
| 138 |
EOF |
| 139 |
</pre></div> |
| 140 |
|
| 141 |
<!-- |
| 142 |
export GRASS_FONT=sans # fixes bad default font |
| 143 |
d.mon start=cairo output=plot.png width=400 height=400 |
| 144 |
d.erase # previous image is not cleaned |
| 145 |
--> |
| 146 |
|
| 147 |
<p> |
| 148 |
The next command sequence creates a file <code>plot.png</code> in the current |
| 149 |
directory which is the drawing made by <em>d.linegraph</em>. |
| 150 |
|
| 151 |
<div class="code"><pre> |
| 152 |
d.mon start=cairo output=plot.png width=400 height=400 |
| 153 |
d.linegraph x_file=x.txt y_file=y1.txt,y2.txt |
| 154 |
d.mon stop=cairo |
| 155 |
</pre></div> |
| 156 |
|
| 157 |
<h2>SEE ALSO</h2> |
| 158 |
|
| 159 |
<em> |
| 160 |
<a href="d.frame.html">d.frame</a>, |
| 161 |
<a href="d.text.html">d.text</a>, |
| 162 |
<a href="v.label.html">v.label</a>, |
| 163 |
<a href="d.graph.html">d.graph</a>, |
| 164 |
<a href="d.histogram.html">d.histogram</a> |
| 165 |
</em> |
| 166 |
|
| 167 |
<h2>AUTHOR</h2> |
| 168 |
|
| 169 |
Chris Rewerts, Agricultural Engineering, Purdue University |