Context Navigation

plot @ 1619

Last change on this file since 1619 was 1619, checked in by dkearney, 14 years ago
updating python objects api with example code, fixes for tcl objects api
File size: 19.6 KB

Line
1	Rappture::Plot
2
3	constructors/destructors
4	Rappture::Plot <lib>
5	Rappture::Plot <plotObj>
6
7	methods
8	name ?<val>?
9	path ?<val>?
10	label ?<val>?
11	desc ?<val>?
12	hints ?<val>?
13	color ?<val>?
14	property <key> ?<val>?
15	propremove <key>
16	add <x> <y> -format <fmt> -name <name>
17	add <c> -name <name>
18	count
19	curve <name>
20	getNthCurve <n>
21	vvalue ?<hints>?
22	random
23	diff <o>
24	configure -as <as> <c>
25	dump -as <as>
26	outcome
27	is
28
29	---------------------------------------
30	Rappture::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	set lib [Rappture::Library]
39	set p [Rappture::Plot $lib]
40	}}}
41
42	Rappture::Plot <plotObj>
43	Purpose: construct a plot object based on plot object plotObj
44	Input Arguments: 1
45	1. plotObj - plot object to copy
46	Return Value: a newly created plot object
47	Notes: None
48	Code Example:
49	{{{
50	set lib [Rappture::Library]
51	set p1 [Rappture::Plot $lib]
52	set p2 [Rappture::Plot $p1]
53	}}}
54
55
56	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, an empty string 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	set p [Rappture::Plot]
68	$p name
69	# ""
70	$p name "fdfactor"
71	$p name
72	# "fdfactor"
73	}}}
74
75	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, an empty string 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	set p [Rappture::Plot]
87	$p path
88	# ""
89	$p path "output"
90	$p path
91	# "output"
92	}}}
93
94	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, an empty string 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	set p [Rappture::Plot]
105	$p label
106	# ""
107	$p label "Fermi-Dirac Factor"
108	$p label
109	# "Fermi-Dirac Factor"
110	}}}
111
112	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, an empty string 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	set 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
132	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, an empty string 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	set p [Rappture::Plot]
143	$p hints
144	# ""
145	$p hints "no hints"
146	$p hints
147	# "no hints"
148	}}}
149
150	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, an empty string 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	set p [Rappture::Plot]
161	$p color
162	# ""
163	$p color "no color"
164	$p color
165	# "no color"
166	}}}
167
168	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	set p [Rappture::Plot]
178	$p property "name"
179	# ""
180	$p property "name" "fdfactor"
181	# "fdfactor"
182	$p name
183	# "fdfactor"
184	}}}
185
186	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	set 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
204	add <x> <y> -format <fmt> -name <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	for {set i 0} {$i < 10} {incr i} {
218	lappend x $i
219	lappend y [expr pow($i,2)]
220	}
221
222	set p [Rappture::Plot]
223	$p add $x $y -format "g:o" -name "xsquared"
224	# a single curve, named "xsquared", is stored in the plot object
225	}}}
226
227	add <c> -name <name>
228	Purpose: add a Curve object to this Plot object
229	Input Arguments: 2
230	1. c - Curve object to add
231	2. name - id of the Curve object
232	Return Value: Outcome object
233	Notes: Curve object should not be deleted by user?
234	Code Example:
235	{{{
236	for {set i 0} {$i < 10} {incr i} {
237	lappend x $i
238	lappend y [expr pow($i,2)]
239	}
240
241	set c [Rappture::Curve]
242
243	$c axis -name "xvals" -label "X Values" \
244	-desc "Values along the X axis" $x
245
246	$c axis -name "yvals" -label "Y Values" \
247	-desc "Values along the Y axis" $y
248
249	set p [Rappture::Plot]
250	$p add $c -name "xsquared"
251	# a single curve, named "xsquared", is stored in the plot object
252	}}}
253
254	count
255	Purpose: retrieve the number of curves in this Plot object
256	Input Arguments: 0
257	Return Value: number of curves stored in the object
258	Notes: None
259	Code Example:
260	{{{
261	for {set i 0} {$i < 10} {incr i} {
262	lappend x $i
263	lappend y1 [expr pow($i,2)]
264	lappend y2 [expr pow($i,3)]
265	}
266
267	set p [Rappture::Plot]
268	$p add $x $y1 -format "g:o" -name "xsquared"
269	$p add $x $y2 -format "b-o" -name "xcubed"
270	puts [$p count]
271	# 2
272	}}}
273
274	curve <name>
275	Purpose: retrieve the curve with the id matching "name"
276	Input Arguments: 1
277	1. name - id to Curve to be retrieved
278	Return Value: Curve object matching "name" or None
279	Notes: None
280	Code Example:
281	{{{
282	for {set i 0} {$i < 10} {incr i} {
283	lappend x $i
284	lappend y1 [expr pow($i,2)]
285	lappend y2 [expr pow($i,3)]
286	}
287
288	set p [Rappture::Plot]
289	$p add $x $y1 -format "g:o" -name "xsquared"
290	$p add $x $y2 -format "b-o" -name "xcubed"
291	set c [$p curve "xsquared"]
292	puts [$c name]
293	# xsquared
294	}}}
295
296	getNthCurve <n>
297	Purpose: return the n'th curve stored in the object
298	Input Arguments: 1
299	1. n - number of the curve to retrieve
300	Return Value: the n'th Curve object stored in
301	the Plot object or None
302	Notes: Curve indecies start at 0
303	Code Example:
304	{{{
305	for {set i 0} {$i < 10} {incr i} {
306	lappend x $i
307	lappend y1 [expr pow($i,2)]
308	lappend y2 [expr pow($i,3)]
309	}
310
311	set p [Rappture::Plot]
312	$p add $x $y1 -format "g:o" -name "xsquared"
313	$p add $x $y2 -format "b-o" -name "xcubed"
314	set c [$p getNthCurve 1]
315	puts [$c name]
316	# xcubed
317	}}}
318
319	vvalue ?<hints>?
320	Purpose: return the value of the object after applying a
321	varying number of hints about how the value
322	should be configured
323	Input Arguments: variable numbber
324	1. variable number of hints
325	Return Value: value of the object
326	Notes: vvalue will parse out the recognisable hints from
327	va_list arg. Values stored in the object are
328	not changed. Hints should be of the form
329	hintKey=hintVal
330	Code Example:
331	{{{
332	for {set i 0} {$i < 10} {incr i} {
333	lappend x $i
334	lappend y1 [expr pow($i,2)]
335	lappend y2 [expr pow($i,3)]
336	}
337
338	set p [Rappture::Plot]
339	$p add $x $y1 -format "g:o" -name "xsquared"
340	$p add $x $y2 -format "b-o" -name "xcubed"
341	puts [$p vvalue]
342	# [ [ [1 2 3 4 5 6 7 8 9 10] \
343	# [1 4 9 16 25 36 49 64 81 100] ] \
344	# [ [1 2 3 4 5 6 7 8 9 10] \
345	# [1 8 27 64 125 216 343 512 729 1000] ] ]
346
347	}}}
348
349	random
350	Purpose: populate the object with a random value
351	Input Arguments: 0
352	Return Value: None
353	Notes: the current value of this object will be populated
354	with a random value that fits within the min and
355	max if they were specified.
356	Code Example:
357	{{{
358	set p [Rappture::Plot]
359	$p random
360	# plot is filed with random data
361	puts [$p vvalue]
362	# [ [ [1 2 3 4 5 6 7 8 9 10] \
363	# [1 2 3 4 5 6 7 8 9 10] ] \
364	# [ [1 2 3 4 5 6 7 8 9 10] \
365	# [1 4 9 16 25 36 49 64 81 100] ] \
366	# [ [1 2 3 4 5 6 7 8 9 10] \
367	# [1 8 27 64 125 216 343 512 729 1000] ] ]
368	puts [$p count]
369	# 3
370
371	}}}
372
373	diff <o>
374	Purpose: return a list showing the differences between
375	this object and Rappture Object o
376	Input Arguments: 1
377	1. o - Rappture Object to diff against
378	Return Value: list of differences between objects
379	Notes: None
380	Code Example:
381	{{{
382	set p1 [Rappture::Plot]
383	$p1 random
384	# plot is filed with random data
385	puts [$p vvalue]
386	# [ [ [1 2 3 4 5 6 7 8 9 10] \
387	# [1 4 9 16 25 36 49 64 81 100] ] ]
388
389	set p2 [Rappture::Plot]
390	$p2 random
391	# plot is filed with random data
392	puts [$p vvalue]
393	# [ [ [1 2 3 4 5 6 7 8 9 10] \
394	# [1 8 27 64 125 216 343 512 729 1000] ] ]
395
396	set diffs [$p1 diff $p2]
397
398	foreach {ctype prop oVal nVal} $diffs {
399	puts "$ctype $prop $oval $nVal"
400	}
401	# c name temperature Ef
402	# c units K eV
403	# c def 300 4.5
404	# c min 0 0
405	# c max 500 10
406	# c label "Ambiant Temperature" "Fermi Level"
407	# c desc "Temperature of the environment" "Energy at center of distribution"
408	#
409	# Note that this function will find a difference in the
410	# minimum values even though they are numerically equal.
411	# This is because the objects have different units that
412	# are not compatible. If compatible units were found,
413	# n2's values would have been converted to n1's units
414	# for each comparison.
415
416
417	}}}
418
419	configure -as <as> <c>
420	Purpose: configure the object based on the data in "c".
421	use "as" to determine the type of data in "c".
422	Input Arguments: 2
423	1. as - type of data stored in "c".
424	valid values include:
425	RPCONFIG_XML
426	RPCONFIG_TREE
427	2. c - data to configure the object from.
428	if as is... then c should be...
429	RPCONFIG_XML const char *xmltext
430	RPCONFIG_TREE RP_ParserXML *object
431	Return Value: None
432	Notes: object is configured based on values in "c"
433	Code Example:
434	{{{
435	set p [Rappture.Plot]
436	set xmldata {
437	<?xml version="1.0">
438	<curve id="xsquared">
439	<about>
440	<group>auto34</group>
441	<label>x squared</label>
442	<description>x values are squared</description>
443	<type></type>
444	<format>g:o</format>
445	</about>
446	<xaxis>
447	<label>x values</label>
448	<description>values being squared</description>
449	<units></units>
450	<scale>linear</scale>
451	</xaxis>
452	<yaxis>
453	<label>y values</label>
454	<description>squared values</description>
455	<units></units>
456	<scale>linear</scale>
457	</yaxis>
458	<component>
459	<xy> 1 1
460	2 4
461	3 9
462	4 16
463	5 25
464	6 36
465	7 49
466	8 64
467	9 81
468	10 100
469	</xy>
470	</component>
471	</curve>
472	<curve id="xcubed">
473	<about>
474	<group>auto34</group>
475	<label>x cubed</label>
476	<description>x values are cubed</description>
477	<type></type>
478	<format>b-o</format>
479	</about>
480	<xaxis>
481	<label>x values</label>
482	<description>values being cubed</description>
483	<units></units>
484	<scale>linear</scale>
485	</xaxis>
486	<yaxis>
487	<label>y values</label>
488	<description>cubed values</description>
489	<units></units>
490	<scale>linear</scale>
491	</yaxis>
492	<component>
493	<xy> 1 1
494	2 8
495	3 27
496	4 64
497	5 125
498	6 216
499	7 343
500	8 512
501	9 729
502	10 1000
503	</xy>
504	</component>
505	</curve>
506	}
507
508	$p configure -as RPCONFIG_XML $xmldata
509	puts [$p vvalue]
510	# [ [ [1 2 3 4 5 6 7 8 9 10] \
511	# [1 4 9 16 25 36 49 64 81 100] ] \
512	# [ [1 2 3 4 5 6 7 8 9 10] \
513	# [1 8 27 64 125 216 343 512 729 1000] ] ]
514
515	for {set cur 0} {$cur < [$p count]} {incr cur} {
516	set c [$p getNthCurve $cur]
517	puts [$c name]
518	puts [$c label]
519	puts [$c desc]
520	puts [$c format]
521	for {set axisCnt 0} {$axisCnt < [$c dims]} {incr axisCnt} {
522	set axis [$c getNthAxis $axisCnt]
523	puts [$axis label]
524	puts [$axis desc]
525	puts [$axis units]
526	puts [$axis scale]
527	puts [$axis data]
528	}
529	}
530	# xsquared
531	# x squared
532	# x values are squared
533	# g:o
534	# xaxis
535	# x values
536	# values being squared
537	#
538	# linear
539	# [1 2 3 4 5 6 7 8 9 10]
540	# yaxis
541	# y values
542	# squared values
543	#
544	# linear
545	# [1 4 9 16 25 36 49 64 81 100]
546	# xcubed
547	# x cubed
548	# x values are cubed
549	# b-o
550	# xaxis
551	# x values
552	# values being cubed
553	#
554	# linear
555	# [1 2 3 4 5 6 7 8 9 10]
556	# yaxis
557	# y values
558	# cubed values
559	#
560	# linear
561	# [1 8 27 64 125 216 343 512 729 1000]
562
563	}}}
564
565	dump -as <as>
566	Purpose: dump the object values.
567	use "as" to determine how to dump the data.
568	Input Arguments: 2
569	1. as - type of data to be returned.
570	valid values include:
571	RPCONFIG_XML
572	RPCONFIG_TREE
573	Return Value:
574	if as is... then return the following...
575	RPCONFIG_XML ClientDataXml *object
576	RPCONFIG_TREE RP_ParserXML *object
577	Notes: None
578	Code Example:
579	{{{
580	for {set i 0} {$i < 10} {incr i} {
581	lappend x $i
582	lappend y1 [expr pow($i,2)]
583	lappend y2 [expr pow($i,3)]
584	}
585
586	set p [Rappture::Plot]
587	$p add $x $y1 -format "g:o" -name "xsquared"
588	$p add $x $y2 -format "b-o" -name "xcubed"
589	puts [$p dump -as RPCONFIG_XML]
590	# <curve id="xsquared">
591	# <about>
592	# <group>auto34</group>
593	# <label></label>
594	# <description></description>
595	# <type>(null)</type>
596	# <format>g:o</format>
597	# </about>
598	# <xaxis>
599	# <label></label>
600	# <description></description>
601	# <units></units>
602	# <scale>linear</scale>
603	# </xaxis>
604	# <yaxis>
605	# <label></label>
606	# <description></description>
607	# <units></units>
608	# <scale>linear</scale>
609	# </yaxis>
610	# <component>
611	# <xy> 1 1
612	# 2 4
613	# 3 9
614	# 4 16
615	# 5 25
616	# 6 36
617	# 7 49
618	# 8 64
619	# 9 81
620	# 10 100
621	# </xy>
622	# </component>
623	# </curve>
624	# <curve id="xcubed">
625	# <about>
626	# <group>auto34</group>
627	# <label></label>
628	# <description></description>
629	# <type>(null)</type>
630	# <format>b-o</format>
631	# </about>
632	# <xaxis>
633	# <label></label>
634	# <description></description>
635	# <units></units>
636	# <scale>linear</scale>
637	# </xaxis>
638	# <yaxis>
639	# <label></label>
640	# <description></description>
641	# <units></units>
642	# <scale>linear</scale>
643	# </yaxis>
644	# <component>
645	# <xy> 1 1
646	# 2 8
647	# 3 27
648	# 4 64
649	# 5 125
650	# 6 216
651	# 7 343
652	# 8 512
653	# 9 729
654	# 10 1000
655	# </xy>
656	# </component>
657	# </curve>
658
659	}}}
660
661	outcome
662	Purpose: return the status of this object as an Outcome.
663	Input Arguments: 0
664	Return Value: status of the object as an Outcome
665	Notes: None
666	Code Example:
667	{{{
668	set p [Rappture::Plot]
669	set out [$p outcome]
670	if ([$out value] != 0) {
671	puts stderr [$out context]
672	puts stderr [$out remark]
673	}
674	}}}
675
676
677	is
678	Purpose: return an integer tag describing the object.
679	Input Arguments: 0
680	Return Value: integer tag unique to all number objects
681	Notes: None
682	Code Example:

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format