Debian Codegraph @

display/d.linegraph/d.linegraph.html

raw
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 &gt; x.txt &lt;&lt;EOF
119 1
120 3
121 4
122 6
123 9
124 EOF
125 cat &gt; y1.txt &lt;&lt;EOF
126 50
127 58
128 65
129 34
130 27
131 EOF
132 cat &gt; y2.txt &lt;&lt;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