Context Navigation

plot @ 1619

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

Line
1	Rappture.Plot
2
3	constructors/destructors
4	Rappture.Plot([lib])
5	Rappture.Plot(o)
6
7	methods
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	---------------------------------------
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	lib = Rappture.Library()
39	p = Rappture.Plot(lib)
40	}}}
41
42	Rappture.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
56	p.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
75	p.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
94	p.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
112	p.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
132	p.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
150	p.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
168	p.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
186	p.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
204	p.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
228	p.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
256	p.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
279	p.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
304	p.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
330	p.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
363	p.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
387	p.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[(i4):(i4)+4]
434	# print ctype, prop, oVal, nVal
435
436	}}}
437
438	p.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
582	p.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
682	p.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
698	p.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.

Download in other formats:

Original Format