Debian Codegraph @

texmf-dist/doc/latex/numericplots/src/BasicFunctionality.tex

raw
1 % Copyright 2010 Thomas Koenig, Alexander Michel
2 %
3 % This file is part of NumericPlots.
4 %
5 % NumericPlots is free software: you can redistribute it and/or modify
6 % it under the terms of the GNU General Public License as published by
7 % the Free Software Foundation, either version 3 of the License, or
8 % any later version.
9 %
10 % NumericPlots is distributed in the hope that it will be useful,
11 % but WITHOUT ANY WARRANTY; without even the implied warranty of
12 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 % GNU General Public License for more details.
14 %
15 % You should have received a copy of the GNU General Public License
16 % along with NumericPlots. If not, see <http://www.gnu.org/licenses/>.
17
18 \part{Using the package}
19
20 \section{Basic Functionality}
21
22 The package NumericPlots\\
23 \verb+\usepackage{NumericPlots}+
24 \\
25 is intended to be used to plot numeric data which
26 may, e.g., be exported from Matlab by export2latex.m. The data must be defined
27 in the form
28 \lstinputlisting[lastline=9]{examples/DefineData}
29 where the first column contains the x, the second column the y-data.
30
31 \emph{Please note that the package relies on the \texttt{listplot}-command from
32 pstricks!}
33
34 \subsection{plots}
35
36
37 The easiest plot may be done by
38
39 \begin{minipage}[T]{0.45\linewidth}
40 \lstinputlisting{examples/basic_EasyPlot}
41 \end{minipage}
42 \hspace{0.05\linewidth}
43 \begin{minipage}[T]{0.45\linewidth}
44 \input{examples/basic_EasyPlot}
45 \end{minipage}
46
47 if you want to add a legend, you simply call
48
49 \begin{minipage}[T]{0.45\linewidth}
50 \lstinputlisting{examples/basic_Legend}
51 \end{minipage}
52 \hspace{0.05\linewidth}
53 \begin{minipage}[T]{0.45\linewidth}
54 \input{examples/basic_Legend}
55 \end{minipage}
56
57 To plot multiple data in one plot call
58
59 \begin{minipage}[T]{0.45\linewidth}
60 \lstinputlisting{examples/basic_MultipleData}
61 \end{minipage}
62 \hspace{0.05\linewidth}
63 \begin{minipage}[T]{0.45\linewidth}
64 \centering
65 \input{examples/basic_MultipleData}
66 \end{minipage}
67
68
69 \subsection{Label and TickLabels}
70
71 The commands \texttt{plotxAxis} and \texttt{plotyAxis} take the options
72 \texttt{NoLabel}, \texttt{NoTicks}, \texttt{NoTickLabel} as well as
73 \texttt{LabelOption} and \texttt{TickLabelOption} which may be used to eliminate
74 or change the look of the labels.
75
76 Standard values for \texttt{LabelOption} and \texttt{TickLabelOption} may be set\\
77 by \verb|\newcommand{\StdLabelOption}{\color{blue}|\\
78 and \verb|\newcommand{\StdTickLabelOption}{\small}|.
79
80 The option \texttt{LabelSep} may be used for \verb|\plotxAxis| and
81 \verb|\plotyAxis| to set the seperation between the axis and the label. Standard
82 value is \verb|\baselineskip+1ex| for the x-label and \verb|7ex| for the
83 y-label.
84
85 \begin{minipage}[T]{0.45\linewidth}
86 \lstinputlisting{examples/basic_Labels}
87 \end{minipage}
88 \hspace{0.05\linewidth}
89 \begin{minipage}[T]{0.45\linewidth}
90 \input{examples/basic_Labels}
91 \end{minipage}
92
93 It is furthermore possible to change the position and the rotation of the labels
94 and tick labels, see the example in section \ref{sec:Details:Labels}.
95
96 It is also possible to put single tick labels, see the example in section
97 \ref{sec:Details:Labels}.
98
99 \subsection{Place ``Objects'' in the plot.}\label{sec:PlaceObjects}
100
101 There are basically two different options to place objects in the plot. To
102 understand the difference one has to keep in mind that the axis have two
103 different coordinate systems. One is the system defined by xMin, xMax, yMin and
104 yMax (refered to as ``DataCoordinateSystem''), the other ist the system defined
105 by xCoordMin, xCoordMax, yCoordMin and yCoordMax (refered to as
106 ``PictureCoordinateSystem''), see section \ref{sec:MultiplePlots}.
107
108 It is now possible to place stuff in the graph with the DataCoordinates with the
109 command NDPput, see the following example.
110
111 \begin{minipage}[T]{0.45\linewidth}
112 \lstinputlisting{examples/basic_PlaceObjects}
113 \end{minipage}
114 \hspace{0.05\linewidth}
115 \begin{minipage}[T]{0.45\linewidth}
116 \input{examples/basic_PlaceObjects}
117 \end{minipage}
118
119
120 For convenience the commands \verb|\putXX{object}| where
121 $XX\in\left(N,S,E,W,NW,NE,SW,SE\right)$ are defined to place something in the
122 North, South,\ldots, SouthEast corner of the plot. Also, the command
123 \verb|\putExpY{xx}| and \verb|\putExpX{xx}| may be used to place exponents at
124 the axes.
125
126 \begin{minipage}[T]{0.45\linewidth}
127 \lstinputlisting[firstline=14,lastline=24]{examples/basic_PlaceObjectsII}
128 \end{minipage}
129 \hspace{0.05\linewidth}
130 \begin{minipage}[T]{0.45\linewidth}
131 \input{examples/basic_PlaceObjectsII}
132 \end{minipage}
133
134 Alternatively, stuff can be placed
135 within the plot with \verb|\rput|.
136
137
138 \begin{minipage}[T]{0.5\linewidth}
139 \lstinputlisting[firstline=14,lastline=28]{examples/basic_UseRput}
140 \end{minipage}
141 \begin{minipage}[T]{0.5\linewidth}
142 \input{examples/basic_UseRput}
143 \end{minipage}
144
145
146 % =================================
147 % | |
148 % | Linestyles and colors |
149 % | |
150 % =================================
151
152 \subsection{Linestyles and colors}
153
154 While using the package, there are predefined linestyles which may be used:
155
156 \begin{minipage}{0.55\linewidth}
157 \centering
158 \small
159
160 \begin{NumericDataPlot}[lly=1cm,llx=1cm,urx=0.25cm,ury=0.25cm]{\linewidth}{0.85\linewidth}
161 \setxAxis{xMin=2, xMax=17, xO=5, Dx=4}
162 \setyAxis{yMin=20, yMax=70, yO=20, Dy=20}
163
164 \plotxAxis[NoLabel, AxisStyle=Boxed]{}
165 \plotyAxis[NoLabel, AxisStyle=Boxed]{}
166
167 \listplot[style=StdLineStyA]{\DataA}
168 \listplot[style=StdLineStyB]{\DataB}
169 \listplot[style=StdLineStyC]{\DataC}
170 \listplot[style=StdLineStyD]{\DataD}
171 \listplot[style=StdLineStyE]{\DataE}
172 \listplot[style=StdLineStyF]{\DataF}
173 \listplot[style=StdLineStyG]{\DataG}
174 \end{NumericDataPlot}
175 \end{minipage}
176 \begin{minipage}{0.4\linewidth}
177 \centering
178 \LegendDefinition{
179 \LegLine{style=StdLineStyA} & StdLineStyA \\
180 \LegLine{style=StdLineStyB} & StdLineStyB \\
181 \LegLine{style=StdLineStyC} & StdLineStyC \\
182 \LegLine{style=StdLineStyD} & StdLineStyD \\
183 \LegLine{style=StdLineStyE} & StdLineStyE \\
184 \LegLine{style=StdLineStyF} & StdLineStyF \\
185 \LegLine{style=StdLineStyG} & StdLineStyG \\
186 }
187 \end{minipage}
188
189 When using the package option \texttt{BW} the standard line styles will be
190 replaced by their black and white counterparts:
191
192 \begin{minipage}{0.6\linewidth}
193 \centering
194 \small
195
196 \begin{NumericDataPlot}[lly=1cm,llx=1cm,urx=0.25cm,ury=0.25cm]{\linewidth}{0.85\linewidth}
197 \setxAxis{xMin=2, xMax=17, xO=5, Dx=4}
198 \setyAxis{yMin=20, yMax=70, yO=20, Dy=20}
199
200 \plotxAxis[NoLabel, AxisStyle=Boxed]{}
201 \plotyAxis[NoLabel, AxisStyle=Boxed]{}
202
203 \listplot[style=BWStdLineStyA]{\DataA}
204 \listplot[style=BWStdLineStyB]{\DataB}
205 \listplot[style=BWStdLineStyC]{\DataC}
206 \listplot[style=BWStdLineStyD]{\DataD}
207 \listplot[style=BWStdLineStyE]{\DataE}
208 \listplot[style=BWStdLineStyF]{\DataF}
209 \listplot[style=BWStdLineStyG]{\DataG}
210 \end{NumericDataPlot}
211 \end{minipage}
212 \begin{minipage}{0.4\linewidth}
213 \centering
214 \LegendDefinition{
215 \LegLine{style=BWStdLineStyA} & BWStdLineStyA \\
216 \LegLine{style=BWStdLineStyB} & BWStdLineStyB \\
217 \LegLine{style=BWStdLineStyC} & BWStdLineStyC \\
218 \LegLine{style=BWStdLineStyD} & BWStdLineStyD \\
219 \LegLine{style=BWStdLineStyE} & BWStdLineStyE \\
220 \LegLine{style=BWStdLineStyF} & BWStdLineStyF \\
221 \LegLine{style=BWStdLineStyG} & BWStdLineStyG \\
222 }
223 \end{minipage}
224
225 For values which are nearly the same (reference and measurement, e.g.) the
226 following line styles may be used:
227
228 \begin{minipage}{0.58\linewidth}
229 \centering
230 \small
231
232 \begin{NumericDataPlot}[lly=1cm,llx=1cm,urx=0.25cm,ury=0.25cm]{\linewidth}{0.85\linewidth}
233 \setxAxis{xMin=2, xMax=17, xO=5, Dx=4}
234 \setyAxis{yMin=20, yMax=70, yO=20, Dy=20}
235
236 \plotxAxis[NoLabel, AxisStyle=Boxed]{}
237 \plotyAxis[NoLabel, AxisStyle=Boxed]{}
238
239 \listplot[style=StdLineStyX]{\DataC}
240 \listplot[style=StdLineStyY]{\DataC}
241
242 \listplot[style=BWStdLineStyX]{\DataD}
243 \listplot[style=BWStdLineStyY]{\DataD}
244 \end{NumericDataPlot}
245 \end{minipage}
246 \begin{minipage}{0.38\linewidth}
247 \centering
248 \LegendDefinition{
249 \LegLine{style=StdLineStyX} & StdLineStyX \\
250 \LegLine{style=StdLineStyY} & StdLineStyY \\
251 \LegLine{style=BWStdLineStyX} & BWStdLineStyX \\
252 \LegLine{style=BWStdLineStyY} & BWStdLineStyY \\
253 }
254 \end{minipage}
255
256 It is, of course, possible to redefine the available linestyles or to define new
257 linestyles.
258
259 \begin{minipage}[T]{0.48\linewidth}
260 \lstinputlisting[firstline=4,lastline=26]{examples/basic_UserLinestyles}
261 \end{minipage}
262 \begin{minipage}[T]{0.48\linewidth}
263 \input{examples/basic_UserLinestyles}
264 \end{minipage}
265
266
267
268 % =================================
269 % | |
270 % | Legend |
271 % | |
272 % =================================
273
274 \subsection{Legend}
275
276 The legend may be created with \verb|\LegendDefinition|. The command takes the
277 two optional arguments \texttt{nrCols} and \texttt{LabelOrientation=[l|c|r]}.
278 The mandatory argument is the definition of a table as demonstrated in the
279 follwing examples.
280
281 \begin{minipage}[T]{0.5\linewidth}
282 \lstinputlisting{examples/basic_LegendI}
283 \end{minipage}
284 \hspace{1ex}
285 \begin{minipage}[T]{0.4\linewidth}
286 \input{examples/basic_LegendI}
287 \end{minipage}
288
289 \begin{minipage}[T]{0.5\linewidth}
290 \lstinputlisting{examples/basic_LegendII}
291 \end{minipage}
292 \hspace{1ex}
293 \begin{minipage}[T]{0.4\linewidth}
294 \input{examples/basic_LegendII}
295 \end{minipage}
296
297 \begin{minipage}[T]{0.5\linewidth}
298 \lstinputlisting{examples/basic_LegendIII}
299 \end{minipage}
300 \hspace{1ex}
301 \begin{minipage}[T]{0.4\linewidth}
302 \input{examples/basic_LegendIII}
303 \end{minipage}
304
305
306 \subsection{Add Lines to the Plot}
307
308 Horizontal and vertical lines may be added to the plot with the commands
309 \verb|\NDPhline{coord}|, \verb|\NDPvline{coord}| and \verb|\NDPline{coord}|. It is also possible to put
310 nodes and draw lines between them, see section \ref{sec:PlaceObjects}.
311
312 \begin{minipage}[T]{0.5\linewidth}
313 \lstinputlisting[firstline=14,lastline=17]{examples/basic_Lines}
314 \end{minipage}
315 \hspace{1ex}
316 \begin{minipage}[T]{0.4\linewidth}
317 \input{examples/basic_Lines}
318 \end{minipage}
319
320
321 \subsection{Add Boxes to the Plot}
322
323 Horizontal and vertical boxes may be added to the plot with the commands
324 \verb|\NDPhbox{coord}|, \verb|\NDPvbox{coord}| and \verb|\NDPbox{coord}|. It is also possible to put
325 nodes and draw lines between them, see section \ref{sec:PlaceObjects}.
326
327 \begin{minipage}[T]{0.5\linewidth}
328 \lstinputlisting[firstline=11,lastline=21]{examples/basic_Boxes}
329 \end{minipage}
330 \hspace{1ex}
331 \begin{minipage}[T]{0.4\linewidth}
332 \input{examples/basic_Boxes}
333 \end{minipage}
334
335
336 \subsection{Grid}
337
338 As shwon in the example below, it is possible to plot a fine grid but not have a
339 tick label at each of the grid lines. While the options \texttt{Dx} and
340 \texttt{Dy} define the distance between the grid lines, the options \texttt{DDx}
341 and \texttt{DDy} define the distance between the tick labels. If \texttt{DDx} or
342 \texttt{DDy} are not set, they take the values of \texttt{Dx} and \texttt{Dy}.
343
344 One may choose not to plot the grid with
345 the option \texttt{NoGrid} for the commands \verb|\plotxAxis| and \verb|\plotyAxis|.
346
347 If the grid is plottet with the axis it may happen that the grid is plottet over
348 the axis. To avoid this, plot the grid first and then plot the axis as shown.
349
350 \begin{minipage}[T]{0.5\linewidth}
351 \lstinputlisting{examples/basic_Grid}
352 \end{minipage}
353 \hspace{1ex}
354 \begin{minipage}[T]{0.4\linewidth}
355 \input{examples/basic_Grid}
356 \end{minipage}
357
358
359
360 \subsection{Logarithmic axes}
361
362
363 \begin{minipage}[T]{0.5\linewidth}
364 \lstinputlisting{examples/basic_LogarithmicI}
365 \end{minipage}
366 \hspace{1ex}
367 \begin{minipage}[T]{0.4\linewidth}
368 \input{examples/basic_LogarithmicI}
369 \end{minipage}
370
371
372 \begin{minipage}[T]{0.5\linewidth}
373 \lstinputlisting{examples/basic_LogarithmicII}
374 \end{minipage}
375 \hspace{1ex}
376 \begin{minipage}[T]{0.4\linewidth}
377 \input{examples/basic_LogarithmicII}
378 \end{minipage}
379
380
381 \begin{minipage}[T]{0.5\linewidth}
382 \lstinputlisting{examples/basic_LogarithmicIII}
383 \end{minipage}
384 \hspace{1ex}
385 \begin{minipage}[T]{0.4\linewidth}
386 \input{examples/basic_LogarithmicIII}
387 \end{minipage}
388
389
390 \subsection{plots with holes}
391
392 If plotting data, one might not want to plot some part of this data, e.g. if
393 only the data in a certain y-range is interesting. If one chooses to eliminate the
394 invalid data either by using \verb+yStart+ or \verb+yEnd+ or by eliminating the
395 data before the export, pstricks will always connect the last valid point of an
396 interval with the first valid point of the next interval. In Matlab e.g.,
397 invalid data (NaN) is just ignored. This behavior is also possible with NumericPlots and
398 export2latex. If export2latex is called with data which contains NaN and with
399 the option.NaNsplit=true, it will split the data in several intervals and append
400 a consecutive number to the identifier for each interval. The exported yMax,
401 yMin values etc. will still be valid for the whole data-vector. The exported
402 data might look like:
403
404 \begin{verbatim}
405 \expandafter\def\csname DataIdentNrRanges\endcsname{3}
406 \expandafter\def\csname DataIdent1\endcsname{
407 560.00 5.40
408 ...
409 574.72 6.25
410 }
411
412 \expandafter\def\csname DataIdent2\endcsname{
413 588.73 4.78
414 ...
415 609.53 12.09
416 }
417
418
419 \expandafter\def\csname DataIdent3\endcsname{
420 620.56 27.81
421 ...
422 649.56 27.32
423 }
424 \end{verbatim}
425
426
427 \expandafter\def\csname DataIdentNrRanges\endcsname{3}
428 \expandafter\def\csname DataIdent1\endcsname{
429 560.00 5.40
430 560.30 6.25
431 560.59 4.74
432 560.90 6.25
433 561.60 5.18
434 561.65 6.25
435 561.70 4.73
436 562.60 4.75
437 562.63 6.06
438 563.75 6.12
439 563.75 5.00
440 564.50 6.25
441 564.76 4.71
442 564.90 4.88
443 565.51 6.25
444 565.63 5.00
445 566.13 5.69
446 566.61 6.78
447 567.10 4.88
448 567.60 4.89
449 567.66 6.25
450 568.30 4.88
451 568.31 6.25
452 569.10 4.77
453 569.51 6.25
454 569.60 6.13
455 570.35 4.85
456 570.63 6.25
457 570.71 5.00
458 571.30 4.64
459 571.31 6.25
460 572.30 4.66
461 572.62 6.06
462 572.90 5.00
463 572.93 5.61
464 573.68 5.00
465 574.11 6.25
466 574.66 4.76
467 574.72 6.25
468 }
469
470 \expandafter\def\csname DataIdent2\endcsname{
471 588.73 4.78
472 588.90 6.15
473 589.50 4.76
474 589.67 4.90
475 589.74 6.25
476 590.66 5.96
477 590.73 4.55
478 591.25 6.25
479 591.69 4.68
480 592.10 4.91
481 592.31 6.25
482 593.20 6.25
483 593.55 5.36
484 593.64 4.79
485 593.74 6.25
486 594.64 4.74
487 594.75 6.11
488 595.25 4.67
489 595.31 6.12
490 596.00 5.84
491 596.30 11.90
492 597.10 10.69
493 597.20 12.00
494 597.69 12.00
495 598.15 10.00
496 598.50 11.97
497 598.67 10.00
498 599.31 10.00
499 599.69 11.91
500 600.13 12.22
501 600.79 10.79
502 600.83 10.31
503 600.86 11.72
504 601.74 10.56
505 601.80 11.25
506 602.78 11.98
507 602.94 10.00
508 603.72 12.08
509 603.94 10.00
510 604.54 10.00
511 604.70 11.96
512 605.14 11.25
513 605.24 10.83
514 605.69 11.92
515 605.80 10.00
516 606.70 11.72
517 607.03 10.00
518 607.49 11.15
519 607.54 10.00
520 608.23 12.15
521 608.72 10.00
522 609.30 10.87
523 609.53 12.09
524 }
525
526 \expandafter\def\csname DataIdent3\endcsname{
527 620.56 27.81
528 620.78 26.25
529 620.85 27.80
530 621.56 27.32
531 621.74 27.78
532 622.00 27.32
533 622.74 26.36
534 623.08 28.75
535 623.31 27.79
536 623.71 26.31
537 624.05 27.32
538 624.65 27.79
539 625.18 27.83
540 625.45 27.35
541 625.95 27.74
542 626.28 27.30
543 626.75 26.34
544 626.88 27.81
545 627.54 28.75
546 627.72 26.38
547 628.23 27.29
548 628.36 27.74
549 628.88 26.25
550 629.28 27.82
551 629.78 28.84
552 629.93 27.32
553 631.13 26.27
554 631.22 27.76
555 631.94 28.75
556 631.98 27.33
557 632.54 26.25
558 632.66 27.78
559 632.89 27.29
560 633.33 28.88
561 633.76 26.45
562 633.94 27.85
563 634.76 26.33
564 635.14 27.74
565 635.68 27.82
566 635.84 26.35
567 636.08 27.84
568 636.46 27.34
569 637.04 27.74
570 637.19 27.32
571 637.70 27.34
572 638.31 27.84
573 638.50 27.78
574 638.65 27.33
575 639.45 27.79
576 639.83 26.34
577 640.03 27.38
578 640.68 27.83
579 641.45 27.31
580 641.50 27.77
581 642.08 27.80
582 642.18 27.32
583 642.76 27.93
584 642.86 26.25
585 643.75 27.32
586 643.91 27.76
587 644.38 27.30
588 644.74 27.83
589 645.06 27.37
590 645.08 27.80
591 645.80 28.80
592 646.13 26.47
593 646.76 26.57
594 647.09 27.81
595 647.26 27.83
596 647.98 26.25
597 648.20 27.33
598 648.34 28.75
599 648.93 28.91
600 649.56 27.32
601 }
602
603 This data can then easily be plotted using the command\\
604 \verb+\multilistplot{<options>}{<Identifier>}+\footnote{Please notice, that the
605 first argument of multilistplot is a mandatory argument. Also notice, that the
606 second argument ist only the name of the data including ``Data'' but not the
607 command as it would be for the listplot command}.
608 The command will call\\
609 \verb+\listplot[<options>]{\<Identifier>}+ for each of
610 the intervals. The first argument is directly passed to the listplot command which is part of the
611 pstricks package. The second argument is the identifier of the data that should
612 be plotted.
613
614 \begin{minipage}[T]{0.5\linewidth}
615 \lstinputlisting{examples/basic_PlotWHoles}
616 \end{minipage}
617 \hspace{1ex}
618 \begin{minipage}[T]{0.4\linewidth}
619 \input{examples/basic_PlotWHoles}
620 \end{minipage}
621