source: trunk/examples/objects/api/python/plot @ 1619

Last change on this file since 1619 was 1619, checked in by dkearney, 11 years ago

updating python objects api with example code, fixes for tcl objects api

File size: 19.9 KB
Line 
1Rappture.Plot
2
3constructors/destructors
4    Rappture.Plot([lib])
5    Rappture.Plot(o)
6
7methods
8    p.name([val])
9    p.path([val])
10    p.label([val])
11    p.desc([val])
12    p.hints([val])
13    p.color([val])
14    p.property(key[, val])
15    p.propremove(key)
16    p.add(x, y, fmt, name)
17    p.add(c, name)
18    p.count()
19    p.curve(name)
20    p.getNthCurve(n)
21    p.vvalue([...])
22    p.random()
23    p.diff(o)
24    p.configure(as, c)
25    p.dump(as, c)
26    p.outcome()
27    p.is()
28
29---------------------------------------
30Rappture.Plot([lib])
31    Purpose: construct a plot object
32    Input Arguments: at most 1
33        1. lib - Rappture library to associate this plot with
34    Return Value: a newly created, empty plot object
35    Notes: None
36    Code Example:
37    {{{
38        lib = Rappture.Library()
39        p = Rappture.Plot(lib)
40    }}}
41
42Rappture.Plot(o)
43    Purpose: construct a plot object based on plot object o
44    Input Arguments: 1
45        1. o - plot object to copy
46    Return Value: a newly created plot object
47    Notes: None
48    Code Example:
49    {{{
50        lib = Rappture.Library()
51        p1 = Rappture.Plot(lib)
52        p2 = Rappture.Plot(p1)
53    }}}
54
55
56p.name([val])
57    Purpose: get/set the id name of the object
58    Input Arguments: at most 1
59        1. val - new id name
60    Return Value: the name of the object
61    Notes: if no name is set, None will be returned
62           the id name is used to identify this object from
63           all other objects and should be unique
64           val, if provided, is used to set the object name
65    Code Example:
66    {{{
67        p = Rappture.Plot()
68        p.name()
69        # ""
70        p.name("fdfactor")
71        p.name()
72        # "fdfactor"
73    }}}
74
75p.path([val])
76    Purpose: get/set the path of the object
77    Input Arguments: at most 1
78        1. val - new path
79    Return Value: path of the object
80    Notes: if no path is set, None will be returned
81           the path tells where this object sits in the
82           hierarchy of objects.
83           val, if provided, is used to set the object path
84    Code Example:
85    {{{
86        p = Rappture.Plot()
87        p.path()
88        # ""
89        p.path("output")
90        p.path()
91        # "output"
92    }}}
93
94p.label([val])
95    Purpose: get/set the label of the object
96    Input Arguments: at most 1
97        1. val - new label
98    Return Value: label of the object
99    Notes: if no label is set, None will be returned
100           the label is used by the graphical user interface.
101           val, if provided, is used to set the object label
102    Code Example:
103    {{{
104        p = Rappture.Plot()
105        p.label()
106        # ""
107        p.label("Fermi-Dirac Factor")
108        p.label()
109        # "Fermi-Dirac Factor"
110    }}}
111
112p.desc([val])
113    Purpose: get/set the description of the object
114    Input Arguments: at most 1
115        1. val - new description
116    Return Value: description of the object
117    Notes: if no description is set, None will be returned
118           the description is used by the graphical user
119           interface to describe what type of data is being
120           requested and how the input is used.
121           val, if provided, is used to set the object description
122    Code Example:
123    {{{
124        p = Rappture.Plot()
125        p.desc()
126        # ""
127        p.desc("A plot of the Fermi-Dirac Factor")
128        p.desc()
129        # "A plot of the Fermi-Dirac Factor"
130    }}}
131
132p.hints([val])
133    Purpose: get/set the hints of the object
134    Input Arguments: at most 1
135        1. val - new hints
136    Return Value: hints of the object
137    Notes: if no hints are set, None will be returned
138           the hints are used by the graphical user interface
139           val, if provided, is used to set the object hints
140    Code Example:
141    {{{
142        p = Rappture.Plot()
143        p.hints()
144        # ""
145        p.hints("no hints")
146        p.hint()
147        # "no hints"
148    }}}
149
150p.color([val])
151    Purpose: get/set the color of the object
152    Input Arguments: at most 1
153        1. val - new color
154    Return Value: color of the object
155    Notes: if no color is set, None will be returned
156           the color is used by the graphical user interface
157           val, if provided, is used to set the object color
158    Code Example:
159    {{{
160        p = Rappture.Plot()
161        p.color()
162        # ""
163        p.color("no color")
164        p.color()
165        # "no color"
166    }}}
167
168p.property(key[, val])
169    Purpose: get/set a generic property in the property database
170    Input Arguments: at most 2
171        1. key - property name
172        2. val - property value
173    Return Value: value of the property
174    Notes: A copy val is stored in the property database
175    Code Example:
176    {{{
177        p = Rappture.Plot()
178        p.property("name")
179        # ""
180        p.property("name","fdfactor")
181        # "fdfactor"
182        p.name()
183        # "fdfactor"
184    }}}
185
186p.propremove(key)
187    Purpose: remove a property from the property database
188    Input Arguments: 1
189        1. key - property name
190    Return Value: value of the property
191    Notes: None
192    Code Example:
193    {{{
194        p = Rappture.Plot()
195        p.name("fdfactor")
196        p.property("name")
197        # "fdfactor"
198        p.propremove("name")
199        # "fdfactor"
200        p.property("name")
201        # ""
202    }}}
203
204p.add(x, y, fmt, name)
205    Purpose: add data for an xy curve to the plot
206    Input Arguments: 4
207        1. x - list/array representing the x axis
208        2. y - list/array representing the y axis
209        3. fmt - string format of the line
210        4. name - string id of the newly created curve
211    Return Value: Outcome object
212    Notes: format can be something like "g:o" to represent
213            green line, dotted line style, circle marker.
214            this follows matlab's formatting rules.
215    Code Example:
216    {{{
217        x = list()
218        y = list()
219        for i in range(0,10) :
220            x.append(i)
221            y.append(pow(i,2))
222
223        p = Rappture.Plot()
224        p.add(x, y, fmt="g:o", name="xsquared")
225        # a single curve, named "xsquared", is stored in the plot object
226    }}}
227
228p.add(c, name)
229    Purpose: add a Curve object to this Plot object
230    Input Arguments: 2
231        1. c - Curve object to add
232        2. name - id of the Curve object
233    Return Value: Outcome object
234    Notes: Curve object should not be deleted by user?
235    Code Example:
236    {{{
237        x = list()
238        y = list()
239        for i in range(0,10) :
240            x.append(i)
241            y.append(pow(i,2))
242
243        c = Rappture.Curve()
244
245        c.axis(name="xvals", label="X Values",
246                desc="Values along the X axis" val=x)
247
248        c.axis(name="yvals", label="Y Values",
249                desc="Values along the Y axis", val=y)
250
251        p = Rappture.Plot()
252        p.add(c, name="xsquared")
253        # a single curve, named "xsquared", is stored in the plot object
254    }}}
255
256p.count()
257    Purpose: retrieve the number of curves in this Plot object
258    Input Arguments: 0
259    Return Value: number of curves stored in the object
260    Notes: None
261    Code Example:
262    {{{
263        x = list()
264        y1 = list()
265        y2 = list()
266        for i in range(0,10) :
267            x.append(i)
268            y1.append(pow(i,2))
269            y2.append(pow(i,3))
270        }
271
272        p = Rappture.Plot()
273        p.add(x, y1, format="g:o", name="xsquared")
274        p.add(x, y2, format="b-o", name="xcubed")
275        print p.count()
276        # 2
277    }}}
278
279p.curve(name)
280    Purpose: retrieve the curve with the id matching "name"
281    Input Arguments: 1
282        1. name - id to Curve to be retrieved
283    Return Value: Curve object matching "name" or None
284    Notes: None
285    Code Example:
286    {{{
287        x = list()
288        y1 = list()
289        y2 = list()
290        for i in range(0,10) :
291            x.append(i)
292            y1.append(pow(i,2))
293            y2.append(pow(i,3))
294        }
295
296        p = Rappture.Plot()
297        p.add(x, y1, format="g:o", name="xsquared")
298        p.add(x, y2, format="b-o", name="xcubed")
299        c = p.curve("xsquared")
300        print c.name()
301        # xsquared
302    }}}
303
304p.getNthCurve(n)
305    Purpose: return the n'th curve stored in the object
306    Input Arguments: 1
307        1. n - number of the curve to retrieve
308    Return Value: the n'th Curve object stored in
309                  the Plot object or None
310    Notes: None
311    Code Example:
312    {{{
313        x = list()
314        y1 = list()
315        y2 = list()
316        for i in range(0,10) :
317            x.append(i)
318            y1.append(pow(i,2))
319            y2.append(pow(i,3))
320        }
321
322        p = Rappture.Plot()
323        p.add(x, y1, format="g:o", name="xsquared")
324        p.add(x, y2, format="b-o", name="xcubed")
325        c = p.getNthCurve(1)
326        print c.name()
327        # xcubed
328    }}}
329
330p.vvalue([...])
331    Purpose: return the value of the object after applying a
332             varying number of hints about how the value
333             should be configured
334    Input Arguments: variable numbber
335        1. variable number of hints
336    Return Value: value of the object
337    Notes: vvalue will parse out the recognisable hints from
338           va_list arg. Values stored in the object are
339           not changed. Hints should be of the form
340           hintKey=hintVal
341    Code Example:
342    {{{
343        x = list()
344        y1 = list()
345        y2 = list()
346        for i in range(0,10) :
347            x.append(i)
348            y1.append(pow(i,2))
349            y2.append(pow(i,3))
350        }
351
352        p = Rappture.Plot()
353        p.add(x, y1, format="g:o", name="xsquared")
354        p.add(x, y2, format="b-o", name="xcubed")
355        print p.vvalue()
356        # [ [ [1 2 3 4 5 6 7 8 9 10] \
357        #     [1 4 9 16 25 36 49 64 81 100] ] \
358        #   [ [1 2 3 4 5 6 7 8 9 10] \
359        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
360
361    }}}
362
363p.random();
364    Purpose: populate the object with a random value
365    Input Arguments: 0
366    Return Value: None
367    Notes: the current value of this object will be populated
368           with a random value that fits within the min and
369           max if they were specified.
370    Code Example:
371    {{{
372        p = Rappture.Plot()
373        p.random()
374        # plot is filed with random data
375        print p.vvalue()
376        # [ [ [1 2 3 4 5 6 7 8 9 10] \
377        #     [1 2 3 4 5 6 7 8 9 10] ] \
378        #   [ [1 2 3 4 5 6 7 8 9 10] \
379        #     [1 4 9 16 25 36 49 64 81 100] ] \
380        #   [ [1 2 3 4 5 6 7 8 9 10] \
381        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
382        print p.count()
383        # 3
384
385    }}}
386
387p.diff(o);
388    Purpose: return a list showing the differences between
389             this object and Rappture Object o
390    Input Arguments: 1
391        1. o - Rappture Object to diff against
392    Return Value: list of differences between objects
393    Notes: None
394    Code Example:
395    {{{
396        p1 = Rappture.Plot()
397        p1.random()
398        # plot is filed with random data
399        print p.vvalue()
400        # [ [ [1 2 3 4 5 6 7 8 9 10] \
401        #     [1 4 9 16 25 36 49 64 81 100] ] ]
402
403        p2 = Rappture.Plot()
404        p2.random()
405        # plot is filed with random data
406        print p.vvalue()
407        # [ [ [1 2 3 4 5 6 7 8 9 10] \
408        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
409
410        diffs = p1.diff(p2)
411        # diffs is a list of tuples or list of lists.
412
413        for ctype, prop, oVal, nVal in diffs {
414            print "%s %s %s %s" % (ctype, prop, oVal, nVal)"
415        }
416        # c name temperature Ef
417        # c units K eV
418        # c def 300 4.5
419        # c min 0 0
420        # c max 500 10
421        # c label "Ambiant Temperature" "Fermi Level"
422        # c desc "Temperature of the environment" "Energy at center of distribution"
423        #
424        # Note that this function will find a difference in the
425        # minimum values even though they are numerically equal.
426        # This is because the objects have different units that
427        # are not compatible. If compatible units were found,
428        # n2's values would have been converted to n1's units
429        # for each comparison.
430        #
431        # if diffs is a flat list, user would need to write something like this:
432        # for i in range(len(diffs)/4):
433        #     ctype, prop, oVal, nVal = diffs[(i*4):(i*4)+4]
434        #     print ctype, prop, oVal, nVal
435
436    }}}
437
438p.configure(as, c)
439    Purpose: configure the object based on the data in "c".
440             use "as" to determine the type of data in "c".
441    Input Arguments: 2
442        1. as - type of data stored in "c".
443                valid values include:
444                    RPCONFIG_XML
445                    RPCONFIG_TREE
446        2. c - data to configure the object from.
447               if as is...     then c should be...
448               RPCONFIG_XML    const char *xmltext
449               RPCONFIG_TREE   RP_ParserXML *object
450    Return Value: None
451    Notes: object is configured based on values in "c"
452    Code Example:
453    {{{
454        p = Rappture.Plot()
455        xmldata = """
456            <?xml version="1.0">
457            <curve id="xsquared">
458                <about>
459                    <group>auto34</group>
460                    <label>x squared</label>
461                    <description>x values are squared</description>
462                    <type></type>
463                    <format>g:o</format>
464                </about>
465                <xaxis>
466                    <label>x values</label>
467                    <description>values being squared</description>
468                    <units></units>
469                    <scale>linear</scale>
470                </xaxis>
471                <yaxis>
472                    <label>y values</label>
473                    <description>squared values</description>
474                    <units></units>
475                    <scale>linear</scale>
476                </yaxis>
477                <component>
478                    <xy>         1         1
479                 2         4
480                 3         9
481                 4        16
482                 5        25
483                 6        36
484                 7        49
485                 8        64
486                 9        81
487                10       100
488                    </xy>
489                </component>
490            </curve>
491            <curve id="xcubed">
492                <about>
493                    <group>auto34</group>
494                    <label>x cubed</label>
495                    <description>x values are cubed</description>
496                    <type></type>
497                    <format>b-o</format>
498                </about>
499                <xaxis>
500                    <label>x values</label>
501                    <description>values being cubed</description>
502                    <units></units>
503                    <scale>linear</scale>
504                </xaxis>
505                <yaxis>
506                    <label>y values</label>
507                    <description>cubed values</description>
508                    <units></units>
509                    <scale>linear</scale>
510                </yaxis>
511                <component>
512                    <xy>         1         1
513                 2         8
514                 3        27
515                 4        64
516                 5       125
517                 6       216
518                 7       343
519                 8       512
520                 9       729
521                10      1000
522                    </xy>
523                </component>
524            </curve>
525        """
526
527        p.configure(RPCONFIG_XML,xmldata)
528        print p.vvalue()
529        # [ [ [1 2 3 4 5 6 7 8 9 10] \
530        #     [1 4 9 16 25 36 49 64 81 100] ] \
531        #   [ [1 2 3 4 5 6 7 8 9 10] \
532        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
533
534        for cur in range(p.count()):
535            c = p.getNthCurve(cur)
536            print c.name()
537            print c.label()
538            print c.desc()
539            print c.format()
540            for axisCnt in range(c.dims()):
541                axis = c.getNthAxis(axisCnt)
542                print axis.label()
543                print axis.desc()
544                print axis.units()
545                print axis.scale()
546                print axis.data()
547        # xsquared
548        # x squared
549        # x values are squared
550        # g:o
551        # xaxis
552        # x values
553        # values being squared
554        #
555        # linear
556        # [1 2 3 4 5 6 7 8 9 10]
557        # yaxis
558        # y values
559        # squared values
560        #
561        # linear
562        # [1 4 9 16 25 36 49 64 81 100]
563        # xcubed
564        # x cubed
565        # x values are cubed
566        # b-o
567        # xaxis
568        # x values
569        # values being cubed
570        #
571        # linear
572        # [1 2 3 4 5 6 7 8 9 10]
573        # yaxis
574        # y values
575        # cubed values
576        #
577        # linear
578        # [1 8 27 64 125 216 343 512 729 1000]
579
580    }}}
581
582p.dump(as, c)
583    Purpose: dump the object values based to the object "c".
584             use "as" to determine how to dump the data.
585    Input Arguments: 2
586        1. as - type of data stored in "c".
587                valid values include:
588                    RPCONFIG_XML
589                    RPCONFIG_TREE
590        2. c - data to configure the object from.
591               if as is...     then c should be...
592               RPCONFIG_XML    ClientDataXml *object
593               RPCONFIG_TREE   RP_ParserXML *object
594    Return Value: None
595    Notes: None
596    Code Example:
597    {{{
598        x = list()
599        y1 = list()
600        y2 = list()
601        for i in range(0,10) :
602            x.append(i)
603            y1.append(pow(i,2))
604            y2.append(pow(i,3))
605        }
606
607        p = Rappture.Plot()
608        p.add(x, y1, format="g:o", name="xsquared")
609        p.add(x, y2, format="b-o", name="xcubed")
610        print p.dump(RPCONFIG_XML)
611        # <curve id="xsquared">
612        #     <about>
613        #         <group>auto34</group>
614        #         <label></label>
615        #         <description></description>
616        #         <type>(null)</type>
617        #         <format>g:o</format>
618        #     </about>
619        #     <xaxis>
620        #         <label></label>
621        #         <description></description>
622        #         <units></units>
623        #         <scale>linear</scale>
624        #     </xaxis>
625        #     <yaxis>
626        #         <label></label>
627        #         <description></description>
628        #         <units></units>
629        #         <scale>linear</scale>
630        #     </yaxis>
631        #     <component>
632        #         <xy>         1         1
633        #      2         4
634        #      3         9
635        #      4        16
636        #      5        25
637        #      6        36
638        #      7        49
639        #      8        64
640        #      9        81
641        #     10       100
642        #         </xy>
643        #     </component>
644        # </curve>
645        # <curve id="xcubed">
646        #     <about>
647        #         <group>unnamed</group>
648        #         <label></label>
649        #         <description></description>
650        #         <type>(null)</type>
651        #         <format>b-o</format>
652        #     </about>
653        #     <xaxis>
654        #         <label></label>
655        #         <description></description>
656        #         <units></units>
657        #         <scale>linear</scale>
658        #     </xaxis>
659        #     <yaxis>
660        #         <label></label>
661        #         <description></description>
662        #         <units></units>
663        #         <scale>linear</scale>
664        #     </yaxis>
665        #     <component>
666        #         <xy>         1         1
667        #      2         8
668        #      3        27
669        #      4        64
670        #      5       125
671        #      6       216
672        #      7       343
673        #      8       512
674        #      9       729
675        #     10      1000
676        #         </xy>
677        #     </component>
678        # </curve>
679
680    }}}
681
682p.outcome()
683    Purpose: return the status of this object as an Outcome.
684    Input Arguments: 0
685    Return Value: status of the object as an Outcome
686    Notes: None
687    Code Example:
688    {{{
689        p = Rappture.Plot()
690        out = p.outcome()
691        if (out.value() != 0) {
692            sys.stderr.write(out.context())
693            sys.stderr.write(out.remark())
694        }
695    }}}
696
697
698p.is()
699    Purpose: return an integer tag describing the object.
700    Input Arguments: 0
701    Return Value: integer tag unique to all number objects
702    Notes: None
703    Code Example:
Note: See TracBrowser for help on using the repository browser.