source: orange/Orange/doc/reference/output.htm @ 9671:a7b056375472

Revision 9671:a7b056375472, 4.6 KB checked in by anze <anze.staric@…>, 2 years ago (diff)

Moved orange to Orange (part 2)

Line 
1<html> <HEAD>
2<LINK REL=StyleSheet HREF="../style.css" TYPE="text/css">
3<LINK REL=StyleSheet HREF="style-print.css" TYPE="text/css" MEDIA=print>
4<body>
5
6<h1>User defined output formats</h1>
7
8<P>Orange provides a mechanism for specifying new output formats and to even modify the way that objects are printed out by default.</P>
9
10<P>All classes derived from <CODE>Orange</CODE> define the following two output methods.</P>
11
12<P class="section">Methods</P>
13<DL class="attributes">
14<DT>dump(format)</DT>
15<DD>Returns the string that represents the object in the given <CODE>format</CODE>. For instance, to print a <CODE>classifier</CODE> in XML format, use
16<XMP class=code>print classifier.dump("xml")
17</XMP>
18</DD>
19
20<DT>write(format, file)</DT>
21<DD>Writes the object to a file; <CODE>file</CODE> must be an opened file.</DD>
22</DL>
23
24<P>Which are the supported formats? Well ... none - by default. And that's what's great about this: you may specify new output formats, write the corresponding functions and register them. Or let others do it for you. For instance, one can program a module containing functions for representing various classes in XML format and register them correspondingly.</P>
25
26<P>There are two functions that deal with output registration.</P>
27
28<P class="section">Functions</P>
29<DL class="attributes">
30<DT>orange.setoutput(class, format, function)</DT>
31<DD>Sets the function for printing the instances of <CODE>class</CODE> in the given <CODE>format</CODE>. <CODE>class</CODE> can be any Orange class; defining output for some format naturally defines it for the subclasses as well (unless it is overloaded). <CODE>function</CODE> must accept a single argument - an instance of <CODE>class</CODE> and return a string with the instance's representation in the given format. <CODE>format</CODE> can be any string; use format names such as "ps", "xml", "ascii"...</DD>
32
33<DT>orange.removeoutput(class, format)</DT>
34<DD>Removes the output format for the class.</DD>
35</DL>
36
37<P>Output can only be redefined for classes derived from class <CODE>Orange</CODE>; the two classes that are not are <CODE>Value</CODE> and <CODE>Example</CODE>.</P>
38
39<P>For example, here's a simple function for printing a contingency matrix in a tab-delimited format.</P>
40
41<p class="header">part of <A href="output.py">output.py</a></p>
42<XMP class=code>import orange
43
44def printTabDelimContingency(c):
45    if c.innerVariable.varType != orange.VarTypes.Discrete or \
46       c.outerVariable.varType != orange.VarTypes.Discrete:
47        raise "printTabDelimContingency can only handle discrete contingencies"
48
49    res = ""
50    for v in c.innerVariable.values:
51        res += "\t%s" % v
52    res += "\n"
53    for i in range(len(c.outerVariable.values)):
54        res += c.outerVariable.values[i]
55        for v in c[i]:
56            res += "\t%5.3f" % v
57        res += "\n"
58    return res
59</XMP>
60
61
62<P>To register the function with format "tab", we call <CODE>setoutput</CODE>.</P>
63
64<XMP class=code>orange.setoutput(orange.Contingency, "tab", printTabDelimContingency)
65</XMP>
66</P>
67
68<P>Let us now read some data, construct a contingency matrix and print it out.</P>
69
70<p class="header">part of <A href="output.py">output.py</a>
71(uses <a href="monk1.tab">monk1.tab</a>)</p>
72<XMP class=code>data = orange.ExampleTable("monk1")
73cont = orange.ContingencyAttrClass("e", data)
74
75print cont.dump("tab")
76</XMP>
77
78<P>Why is this useful? First, by using standard format names and supporting the format for various classes, you can arrange for a more systematic output. For instance, you can define some XML schema for various classifiers (or use a standard one, such as PMML), program the corresponding functions and set the outputs. Afterwards, you can call <CODE>classifier.write("xml", file)</CODE> for any type of <CODE>classifier</CODE> (as long as it supports xml output. You don't need to care about the type of the classifier.</P>
79
80<P>The other reason is that this mechanism allows you to redefine the standard output. The formats for the standard output are "repr" (used by function <CODE>repr()</CODE> and by reverse quotes) and "str" (used by <CODE>str()</CODE> and the <CODE>print</CODE> statement). When objects are printed in interactive session, the former format is used. The format names are based on Python standard methods for converting values into strings). If you find these messy, always redefine both formats.</P>
81
82<P>So, to make <CODE>print</CODE> call our output function, we set the output by</P>
83
84<p class="header">part of <A href="output.py">output.py</a>
85(uses <a href="monk1.tab">monk1.tab</a>)</p>
86<XMP class=code>orange.setoutput(orange.Contingency, "str", printTabDelimContingency)
87
88print cont
89</XMP> 
Note: See TracBrowser for help on using the repository browser.